org.openlr.binary.BinaryMarshaller Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of openlr-binary Show documentation
The newest version!
package org.openlr.binary;

import org.openlr.locationreference.LocationReference;

import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;

/**
 * The marshaller is responsible for marshalling and unmarshalling location references to and from the OpenLR binary format.
 */
public interface BinaryMarshaller {
    /**
     * Unmarshall a location reference from an input stream.
     *
     * @param inputStream the input stream from which to unmarshall the location reference
     * @return the unmarshalled location reference
     * @throws BinaryMarshallerException if the location reference cannot be unmarshalled
     */
    LocationReference unmarshall(ByteArrayInputStream inputStream) throws BinaryMarshallerException;

    /**
     * Unmarshall a location reference of a known type from an input stream. This method is used when the type
     * of the location reference is known in advance.
     *
     * @param inputStream the input stream from which to unmarshall the location reference
     * @param type the expected class of the location reference
     * @param  the expected type of the location reference
     * @return the unmarshalled location reference in the expected type
     * @throws BinaryMarshallerException if the location reference cannot be unmarshalled
     */
     T unmarshall(ByteArrayInputStream inputStream, Class type) throws BinaryMarshallerException;

    /**
     * Unmarshall a location reference from a byte array.
     *
     * @param bytes the byte array from which to unmarshall the location reference
     * @return the unmarshalled location reference
     * @throws BinaryMarshallerException if the location reference cannot be unmarshalled
     */
    LocationReference unmarshall(byte[] bytes) throws BinaryMarshallerException;

    /**
     * Unmarshall a location reference of a known type from a byte array. This method is used when the type of the
     * location reference is known in advance.
     *
     * @param bytes the byte array from which to unmarshall the location reference
     * @param type the expected class of the location reference
     * @param  the expected type of the location reference
     * @return the unmarshalled location reference in the expected type
     * @throws BinaryMarshallerException if the location reference cannot be unmarshalled
     */
     T unmarshall(byte[] bytes, Class type) throws BinaryMarshallerException;

    /**
     * Unmarshall a location reference from a base 64 string.
     *
     * @param base64String the base 64 string from which to unmarshall the location reference
     * @return the unmarshalled location reference
     * @throws BinaryMarshallerException if the location reference cannot be unmarshalled
     */
    LocationReference unmarshall(String base64String) throws BinaryMarshallerException;

    /**
     * Unmarshall a location reference of a knonwn type from a base 64 string. This method is used when the type
     * of the location reference is known in advance.
     *
     * @param base64String the base 64 string from which to unmarshall the location reference
     * @param type the expected class of the location reference
     * @param  the expected type of the location reference
     * @return the unmarshalled location reference in the expected type
     * @throws BinaryMarshallerException if the location reference cannot be unmarshalled
     */
     T unmarshall(String base64String, Class type) throws BinaryMarshallerException;

    /**
     * Marshall a location reference to an output stream in the binary format.
     *
     * @param locationReference the location reference to marshall
     * @param outputStream the output stream to marshall the location reference to
     * @throws BinaryMarshallerException if the location reference cannot be marshalled
     */
    void marshall(LocationReference locationReference, ByteArrayOutputStream outputStream) throws BinaryMarshallerException;

    /**
     * Marshall a location reference to a byte array.
     *
     * @param locationReference the location reference to marshall
     * @return the marshalled location reference as a byte array
     * @throws BinaryMarshallerException if the location reference cannot be marshalled
     */
    byte[] marshall(LocationReference locationReference) throws BinaryMarshallerException;

    /**
     * Marshall a location reference to a base 64 string.
     *
     * @param locationReference the location reference to marshall
     * @return the marshalled location reference as a base 64 string
     * @throws BinaryMarshallerException if the location reference cannot be marshalled
     */
    String marshallToBase64String(LocationReference locationReference) throws BinaryMarshallerException;
}