Package org.beanio

Interface Marshaller

  • All Superinterfaces:
    Debuggable
    All Known Implementing Classes:
    MarshallerImpl
    public interface Marshaller
extends Debuggable
    Interface for marshalling bean objects.

    A Marshaller can be used to marshal a bean object bound to a record in a mapping file. Marshalling bean objects that span multiple records is not supported and will cause a BeanWriterException.

    Depending on the stream format, a bean object can be marshalled to one or more formats. All stream formats support marshalling to a String value, as shown in the following example:

       marshaller.marshal(object).toString();

    A Marshaller instance is stateful. If a BeanIO mapping file declares record ordering and expected occurrences, a BeanWriterException may be thrown for bean objects written out of sequence or that have exceeded a record's maximum occurrences.

    There is some performance benefit for reusing the same Marshaller instance, but a Marshaller is not thread safe and should not be used to concurrently marshal multiple bean objects.

    Since:
    2.0

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      Marshaller marshal​(java.lang.Object bean)
      Marshals a single bean object.
      Marshaller marshal​(java.lang.String recordName, java.lang.Object bean)
      Marshals a single bean object.
      java.lang.String[] toArray()
      Returns the most recent marshalled bean object as a String[] for csv and delimited formatted streams.
      org.w3c.dom.Document toDocument()
      Returns the most recent marshalled bean object as a Document for xml formatted streams.
      java.util.List<java.lang.String> toList()
      Returns the most recent marshalled bean object as a List for csv and delimited formatted streams.
      java.lang.String toString()
      Returns the most recent marshalled bean object as a String.

    • Method Detail

      • marshal

        Marshaller marshal​(java.lang.Object bean)
            throws BeanWriterException
        Marshals a single bean object.
        Parameters:
        bean - the bean object to marshal
        Returns:
        this Marshaller
        Throws:
        BeanWriterException - if a record is not matched for the given bean object, or in some other rare (but fatal) conditions
        InvalidBeanException - if BeanIO is configured to validate fields during marshalling, and a field does not meet the configured validation rules

      • marshal

        Marshaller marshal​(java.lang.String recordName,
                   java.lang.Object bean)
            throws BeanWriterException
        Marshals a single bean object.
        Parameters:
        recordName - the name of the record to marshal
        bean - the bean object to marshal
        Returns:
        this Marshaller
        Throws:
        BeanWriterException - if a record is not matched for the given record name and bean object, or in some other rare (but fatal) conditions
        InvalidBeanException - if BeanIO is configured to validate fields during marshalling, and a field does not meet the configured validation rules

      • toString

        java.lang.String toString()
                   throws BeanWriterException
        Returns the most recent marshalled bean object as a String. This method is supported by all stream formats.
        Overrides:
        toString in class java.lang.Object
        Returns:
        the record text
        Throws:
        BeanWriterException - if a fatal error occurs

      • toArray

        java.lang.String[] toArray()
                    throws BeanWriterException
        Returns the most recent marshalled bean object as a String[] for csv and delimited formatted streams.
        Returns:
        the String array of fields
        Throws:
        BeanWriterException - if an array is not supported by the stream format

      • toList

        java.util.List<java.lang.String> toList()
                                 throws BeanWriterException
        Returns the most recent marshalled bean object as a List for csv and delimited formatted streams.
        Returns:
        the List of fields
        Throws:
        BeanWriterException - if an array is not supported by the stream format

      • toDocument

        org.w3c.dom.Document toDocument()
                         throws BeanWriterException
        Returns the most recent marshalled bean object as a Document for xml formatted streams.
        Returns:
        the Document
        Throws:
        BeanWriterException - if Document is not supported by the stream format