Interface DataFormat

All Superinterfaces:
AutoCloseable, Service
public interface DataFormat extends Service
Pluggable strategy for converting message bodies to and from a serialised byte-stream format, as described in the Data Format documentation.

A DataFormat is the core abstraction behind the Camel .marshal() and .unmarshal() DSL calls. Camel ships more than 50 data format implementations covering JSON (Jackson, Gson, Fastjson), XML (JAXB, XStream), CSV, Avro, Protobuf, CBOR, and many others. Each data format is a Service; Camel starts and stops it together with the route it is used in, making it safe to hold state (thread-local codec contexts, etc.).

Implementations must be thread-safe unless the enclosing route guarantees single-threaded execution. The unmarshal(Exchange, Object) default method converts the body to an InputStream before delegating to unmarshal(Exchange, java.io.InputStream); override it when a more direct conversion is possible (as camel-jaxb does for String payloads).

See Also:

  • Method Details

    • marshal

      void marshal(Exchange exchange, Object graph, OutputStream stream) throws Exception
      Marshals the object to the given Stream.
      Parameters:
      exchange - the current exchange
      graph - the object to be marshalled
      stream - the output stream to write the marshalled result to
      Throws:
      Exception - can be thrown

    • unmarshal

      Object unmarshal(Exchange exchange, InputStream stream) throws Exception
      Unmarshals the given stream into an object.

      Notice: The result is set as body on the exchange message. It is possible to mutate the message provided in the given exchange parameter. For instance adding headers to the message will be preserved.

      It's also legal to return the same passed exchange as is but also a Message object as well which will be used as the message of exchange.

      Parameters:
      exchange - the current exchange
      stream - the input stream with the object to be unmarshalled
      Returns:
      the unmarshalled object
      Throws:
      Exception - can be thrown
      See Also:

    • unmarshal

      default Object unmarshal(Exchange exchange, Object body) throws Exception
      Unmarshals the given body into an object.

      Notice: The result is set as body on the exchange message. It is possible to mutate the message provided in the given exchange parameter. For instance adding headers to the message will be preserved.

      It's also legal to return the same passed exchange as is but also a Message object as well which will be used as the message of exchange.

      This method can be used when a dataformat is optimized to handle any kind of message body as-is. For example camel-jaxb has been optimized to do this. The regular unmarshal(Exchange, InputStream) method requires Camel to convert the message body into an InputStream prior to calling the unmarshal method. This can be avoided if the data-format implementation can be optimized to handle this by itself, such as camel-jaxb that can handle message body as a String payload out of the box. When a data format implementation is using this method, then the unmarshal(Exchange, InputStream) must also be implemented but should be empty, as Camel will not invoke this method.

      Parameters:
      exchange - the current exchange
      body - the input object to be unmarshalled
      Returns:
      the unmarshalled object
      Throws:
      Exception - can be thrown