com.ibm.as400.data

Class RecordFormatDocument

  • java.lang.Object
    • com.ibm.as400.data.RecordFormatDocument
  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable

    public class RecordFormatDocument
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable
    Supports the use of Record Format Markup Language (RFML) to specify formats and data values for file records and data buffers. RFML is an XML language similar to PCML (Program Call Markup Language). RecordFormatDocument parses an RFML document and allows the application to set and get values of specific fields within a record. The command line interface may be used to serialize RFML document definitions. 
     java com.ibm.as400.data.RecordFormatDocument
     -serialize
     RFML document name
    Options:
    -serialize
    Parses the RFML document and creates a serialized version of the document. The name of the serialized file will match the document name, and the file extension will be .rfml.ser (lowercase).
    rfml document name
    The fully-qualified resource name of the RFML document which defines the record format(s).

    Serialized RFML files
    To increase run-time performance, you can use a serialized RFML file. A serialized RFML file contains serialized Java objects representing the RFML. The objects that are serialized are the same objects that are created when you construct the RecordFormatDocument object from a RFML source file. Using serialized RFML files gives you better performance because the IBM XML parser is not needed at run-time to interpret and validate the RFML tags.

    For usage examples, refer to the PCML section of the Toolbox Programmer's Guide. The behavior of RecordFormatDocument matches that of ProgramCallDocument for methods that have the same name, such as setIntValue() and getIntValue().

    Note: This class requires Java 2 (v1.2.2) or later.

    See Also:
    Serialized Form

    • Method Summary

      Methods 
      Modifier and Type Method and Description
      java.lang.Object clone()
      Creates and returns a copy of this object.
      Descriptor getDescriptor()
      Returns a Descriptor representing the current RFML document.
      static Descriptor getDescriptor(java.lang.String documentName)
      Returns a Descriptor for the specified RFML document.
      static Descriptor getDescriptor(java.lang.String documentName, java.lang.ClassLoader loader)
      Returns a Descriptor representing the specified RFML document.
      double getDoubleValue(java.lang.String name)
      Returns a double value for the named element.
      double getDoubleValue(java.lang.String name, int[] indices)
      Returns a double value for the named element given indices to the data element.
      int getIntValue(java.lang.String name)
      Returns an int value for the named element.
      int getIntValue(java.lang.String name, int[] indices)
      Returns an int value for the named element given indices to the data element.
      java.lang.String getStringValue(java.lang.String name)
      Returns a String value for the named <data type="char"> element.
      java.lang.String getStringValue(java.lang.String name, int type)
      Returns a String value for the named <data type="char"> element.
      java.lang.String getStringValue(java.lang.String name, int[] indices, int type)
      Returns a String value for the named <data type="char"> element, given indices to the data element.
      java.lang.Object getValue(java.lang.String name)
      Returns the Java object value for the named element.
      java.lang.Object getValue(java.lang.String name, int[] indices)
      Returns the Java object value for the named element given indices to the data element.
      static void main(java.lang.String[] args)
      Provides a command line interface to RecordFormatDocument.
      void serialize(java.io.File file)
      Serializes the RecordFormatDocument.
      void serialize(java.io.OutputStream outputStream)
      Serializes the RecordFormatDocument.
      void serialize(java.lang.String fileName)
      Serializes the RecordFormatDocument.
      void setDocument(java.lang.String documentName)
      Sets the RFML document resource.
      void setDocument(java.lang.String documentName, java.lang.ClassLoader loader)
      Sets the RFML document resource.
      void setIntValue(java.lang.String name, int value)
      Sets the Java object value for the named element using an int input value.
      void setIntValue(java.lang.String name, int[] indices, int value)
      Sets the Java object value for the named element using an int input value given indices to the data element.
      void setStringValue(java.lang.String name, int[] indices, java.lang.String value, int type)
      Sets the Java object value for the named <data type="char"> element using a String input value, given indices to the data element.
      void setStringValue(java.lang.String name, java.lang.String value)
      Sets the Java object value for the named <data type="char"> element using a String input.
      void setStringValue(java.lang.String name, java.lang.String value, int type)
      Sets the Java object value for the named <data type="char"> element using a String input.
      void setValue(java.lang.String name, int[] indices, java.lang.Object value)
      Sets the Java object value for the named element given indices to the data element.
      void setValue(java.lang.String name, java.lang.Object value)
      Sets the Java object value for the named element.
      void setValues(java.lang.String formatName, byte[] values)
      Sets the data represented by the specified <recordformat> element.
      void setValues(java.lang.String formatName, Record record)
      Sets the Java object values for the specified <recordformat> element, based on the values stored in the record object passed into the method.
      byte[] toByteArray(java.lang.String formatName)
      Returns the data contained by the specified <recordformat> element, as a byte array.
      Record toRecord(java.lang.String formatName)
      Returns a Record object with the same structure and data as the specified <recordformat> element.
      RecordFormat toRecordFormat(java.lang.String formatName)
      Returns a RecordFormat object with the same structure as the specified <recordformat> element.
      void toXml(java.io.File file)
      Generates XML (RFML) representing the data contained in this object.
      void toXml(java.io.OutputStream outputStream)
      Generates XML (RFML) representing the data contained in this object.
      void toXml(java.lang.String fileName)
      Generates XML (RFML) representing the data contained in this object.

      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • RecordFormatDocument

        public RecordFormatDocument()
        Constructs a RecordFormatDocument.

        Prior to using an object constructed with this method, either setDocument or setValues must be called.

      • RecordFormatDocument

        public RecordFormatDocument(java.lang.String documentName)
                     throws XmlException
        Constructs a RecordFormatDocument. The RFML document resource will be loaded from the classpath. The classpath will first be searched for a serialized resource. If a serialized resource is not found, the classpath will be searched for an RFML source file.
        Parameters:
        documentName - The document resource name of the RFML document for the record formats to be referenced. All RFML-related file extensions are assumed to be lowercase (for example, .rfml or .rfml.ser). The resource name can be a package qualified name. For example, "com.myCompany.myPackage.myRfml"
        Throws:
        XmlException - when the specified RFML document cannot be found.

      • RecordFormatDocument

        public RecordFormatDocument(java.lang.String documentName,
                    java.lang.ClassLoader loader)
                     throws XmlException
        Constructs a RecordFormatDocument. The RFML document resource will be loaded from the classpath of the specified ClassLoader. The classpath will first be searched for a serialized resource. If a serialized resource is not found, the classpath will be searched for an RFML source file.
        Parameters:
        documentName - The document resource name of the RFML document for the record formats to be referenced. All RFML-related file extensions are assumed to be lowercase (for example, .rfml or .rfml.ser). The resource name can be a package qualified name. For example, "com.myCompany.myPackage.myRfml"
        loader - The ClassLoader that will be used when loading the specified document resource.
        Throws:
        XmlException - when the specified RFML document cannot be found.

      • RecordFormatDocument

        public RecordFormatDocument(Record record)
                     throws XmlException
        Constructs a RecordFormatDocument from a Record object.
        Note: The following Record datatypes are not supported by this method:
        Parameters:
        record - The Record object.
        Throws:
        XmlException

      • RecordFormatDocument

        public RecordFormatDocument(RecordFormat recordFormat)
                     throws XmlException
        Constructs a RecordFormatDocument from a RecordFormat object.
        Note: The following Record datatypes are not supported by this method:
        Parameters:
        recordFormat - The RecordFormat object.
        Throws:
        XmlException

    • Method Detail

      • clone

        public java.lang.Object clone()
        Creates and returns a copy of this object.
        Overrides:
        clone in class java.lang.Object
        Returns:
        A copy of this object.

      • getDescriptor

        public static Descriptor getDescriptor(java.lang.String documentName)
                                throws XmlException
        Returns a Descriptor for the specified RFML document. The RFML document resource will be loaded from the classpath. The classpath will first be searched for a serialized resource. If a serialized resource is not found, the classpath will be searched for an RFML source file.
        Parameters:
        documentName - The document resource name of the RFML document for which the Descriptor is returned. The resource name can be a package qualified name. For example, "com.myCompany.myPackage.myRfml"
        Returns:
        A descriptor for the <rfml> element of the named RFML file.
        Throws:
        XmlException - when the specified RFML document cannot be found.

      • getDescriptor

        public static Descriptor getDescriptor(java.lang.String documentName,
                       java.lang.ClassLoader loader)
                                throws XmlException
        Returns a Descriptor representing the specified RFML document. The RFML document resource will be loaded from the classpath. The classpath will first be searched for a serialized resource. If a serialized resource is not found, the classpath will be searched for an RFML source file.
        Parameters:
        documentName - The document resource name of the RFML document for which the Descriptor is returned. The resource name can be a package qualified name. For example, "com.myCompany.myPackage.myRfml"
        loader - The ClassLoader that will be used when loading the specified document resource.
        Returns:
        A descriptor for the <rfml> element of the named RFML file.
        Throws:
        XmlException - when the specified RFML document cannot be found.

      • getDescriptor

        public Descriptor getDescriptor()
        Returns a Descriptor representing the current RFML document.
        Returns:
        A descriptor for the <rfml> element of the current RFML file, or null if the RFML document has not be set.

      • getDoubleValue

        public double getDoubleValue(java.lang.String name)
                      throws XmlException
        Returns a double value for the named element.
        Parameters:
        name - The name of the <data> element in the PCML document.
        Returns:
        The integer value for the named element.
        Throws:
        XmlException - If an error occurs while processing RFML.

      • getDoubleValue

        public double getDoubleValue(java.lang.String name,
                    int[] indices)
                      throws XmlException
        Returns a double value for the named element given indices to the data element. If the data element is an array or is an element in a structure array, an index must be specified for each dimension of the data.
        Parameters:
        name - The name of the <data> element in the PCML document.
        indices - An array of indices for accessing the value of an element in an array.
        Returns:
        The integer value for the named element.
        Throws:
        XmlException - If an error occurs while processing RFML.

      • getIntValue

        public int getIntValue(java.lang.String name)
                throws XmlException
        Returns an int value for the named element.
        Parameters:
        name - The name of the <data> element in the PCML document.
        Returns:
        The integer value for the named element.
        Throws:
        XmlException - If an error occurs while processing RFML.

      • getIntValue

        public int getIntValue(java.lang.String name,
              int[] indices)
                throws XmlException
        Returns an int value for the named element given indices to the data element. If the data element is an array or is an element in a structure array, an index must be specified for each dimension of the data.
        Parameters:
        name - The name of the <data> element in the PCML document.
        indices - An array of indices for accessing the value of an element in an array.
        Returns:
        The integer value for the named element.
        Throws:
        XmlException - If an error occurs while processing RFML.

      • getStringValue

        public java.lang.String getStringValue(java.lang.String name)
                                throws XmlException
        Returns a String value for the named <data type="char"> element. The default bidi string type is assumed (BidiStringType.DEFAULT).
        Parameters:
        name - The name of the <data> element in the RFML document.
        Returns:
        StringValue
        Throws:
        XmlException - If an error occurs while processing RFML.

      • getStringValue

        public java.lang.String getStringValue(java.lang.String name,
                              int type)
                                throws XmlException
        Returns a String value for the named <data type="char"> element.

        This method should be used when the string type cannot be determined until run-time. In those cases, the RFML document cannot be used to indicate the string type so this method can be used to get the value using the string type that is specified.

        Parameters:
        name - The name of the <data> element in the RFML document.
        type - The bidi string type, as defined by the CDRA (Character Data Representation Architecture).
        Returns:
        stringValue
        Throws:
        XmlException - If an error occurs while processing RFML.

      • getStringValue

        public java.lang.String getStringValue(java.lang.String name,
                              int[] indices,
                              int type)
                                throws XmlException
        Returns a String value for the named <data type="char"> element, given indices to the data element. If the data element is an array or is an element in a structure array, an index must be specified for each dimension of the data.

        This method should be used when the string type cannot be determined until run-time. In those cases, the RFML document cannot be used to indicate the string type so this method can be used to get the value using the string type that is specified.

        Parameters:
        name - The name of the <data> element in the RFML document.
        indices - An array of indices for setting the value of an element in an array.
        type - The bidi string type, as defined by the CDRA (Character Data Representation Architecture).
        Returns:
        stringValue
        Throws:
        XmlException - If an error occurs while processing RFML.

      • getValue

        public java.lang.Object getValue(java.lang.String name)
                          throws XmlException
        Returns the Java object value for the named element.

        The type of object returned depends on the description in the RFML document.

        RFML DescriptionObject Returned
        type=charString
        type=bytebyte[]
        type=int
        length=2
        precision=15        		Short
        type=int
        length=2
        precision=16        		Integer
        type=int
        length=4
        precision=31        		Integer
        type=int
        length=4
        precision=32        		Long
        type=int
        length=8
        precision=63        		Long
        type=int
        length=8
        precision=64        		Double
        type=packedBigDecimal
        type=zonedBigDecimal
        type=float
        length=4        		Float
        type=float
        length=8        		Double
        type=structnull
        Parameters:
        name - The name of the <data> element in the RFML document.
        Returns:
        The Java object value for the named <data> element in the RFML document.
        Throws:
        XmlException - If an error occurs while processing RFML.

      • getValue

        public java.lang.Object getValue(java.lang.String name,
                        int[] indices)
                          throws XmlException
        Returns the Java object value for the named element given indices to the data element. If the data element is an array or is an element in a structure array, an index must be specified for each dimension of the data.

        The type of object returned depends on the description in the RFML document.

        Parameters:
        name - The name of the <data> element in the RFML document.
        indices - An array of indices for accessing the value of an element in an array.
        Returns:
        The Java object value for the named <data> element in the RFML document.
        Throws:
        XmlException - If an error occurs while processing RFML.

      • main

        public static void main(java.lang.String[] args)
        Provides a command line interface to RecordFormatDocument. See the class description.
        Parameters:
        args - The arguments.

      • serialize

        public void serialize(java.io.OutputStream outputStream)
               throws java.io.IOException,
                      XmlException
        Serializes the RecordFormatDocument.
        Parameters:
        outputStream - The output stream to which to serialize the object.
        Throws:
        java.io.IOException - If an error occurs while writing to the stream.
        XmlException - If an error occurs while processing RFML.

      • serialize

        public void serialize(java.io.File file)
               throws java.io.IOException,
                      XmlException
        Serializes the RecordFormatDocument.
        Parameters:
        file - The file to which to serialize the object.
        Throws:
        java.io.IOException - If an error occurs while writing to the file.
        XmlException - If an error occurs while processing RFML.

      • serialize

        public void serialize(java.lang.String fileName)
               throws java.io.IOException,
                      XmlException
        Serializes the RecordFormatDocument.
        Parameters:
        fileName - The name of the file to which to serialize the object.
        Throws:
        java.io.IOException - If an error occurs while writing to the file.
        XmlException - If an error occurs while processing RFML.

      • setIntValue

        public void setIntValue(java.lang.String name,
               int value)
                 throws XmlException
        Sets the Java object value for the named element using an int input value.

        The named element must be able to be set using a Integer object.

        Parameters:
        name - The name of the <data> element in the RFML document.
        value - The int value for the named element.
        Throws:
        XmlException - If an error occurs while processing RFML.

      • setIntValue

        public void setIntValue(java.lang.String name,
               int[] indices,
               int value)
                 throws XmlException
        Sets the Java object value for the named element using an int input value given indices to the data element.

        The named element must be able to be set using a Integer object.

        Parameters:
        name - The name of the <data> element in the RFML document.
        indices - An array of indices for setting the value of an element in an array.
        value - The int value for the named element.
        Throws:
        XmlException - If an error occurs while processing RFML.

      • setStringValue

        public void setStringValue(java.lang.String name,
                  java.lang.String value)
                    throws XmlException
        Sets the Java object value for the named <data type="char"> element using a String input. The default bidi string type is assumed (BidiStringType.DEFAULT).
        Parameters:
        name - The name of the <data> element in the RFML document.
        value - The string value for the named element.
        Throws:
        XmlException - If an error occurs while processing RFML.

      • setStringValue

        public void setStringValue(java.lang.String name,
                  java.lang.String value,
                  int type)
                    throws XmlException
        Sets the Java object value for the named <data type="char"> element using a String input.

        This method should be used when the string type cannot be determined until run-time. In those cases, the RFML document cannot be used to indicate the string type so this method can be used to set the value and the string type of the input value.

        Parameters:
        name - The name of the <data> element in the RFML document.
        value - The string value for the named element.
        type - The bidi string type, as defined by the CDRA (Character Data Representation Architecture).
        Throws:
        XmlException - If an error occurs while processing RFML.
        See Also:
        BidiStringType

      • setStringValue

        public void setStringValue(java.lang.String name,
                  int[] indices,
                  java.lang.String value,
                  int type)
                    throws XmlException
        Sets the Java object value for the named <data type="char"> element using a String input value, given indices to the data element.

        This method should be used when the string type cannot be determined until run-time. In those cases, the RFML document cannot be used to indicate the string type so this method can be used to set the value and the string type of the input value.

        Parameters:
        name - The name of the <data> element in the RFML document.
        indices - An array of indices for setting the value of an element in an array.
        value - The string value for the named element.
        type - The bidi string type, as defined by the CDRA (Character Data Representation Architecture).
        Throws:
        XmlException - If an error occurs while processing RFML.

      • setDocument

        public void setDocument(java.lang.String documentName)
                 throws XmlException
        Sets the RFML document resource. The RFML document resource will be loaded from the classpath. The classpath will first be searched for a serialized resource. If a serialized resource is not found, the classpath will be searched for an RFML source file.
        Parameters:
        documentName - The document resource name of the RFML document for the record formats to be referenced. All RFML-related file extensions are assumed to be lowercase (for example, .rfml or .rfml.ser). The resource name can be a package qualified name. For example, "com.myCompany.myPackage.myRfml"
        Throws:
        XmlException - when the specified RFML document cannot be found.

      • setDocument

        public void setDocument(java.lang.String documentName,
               java.lang.ClassLoader loader)
                 throws XmlException
        Sets the RFML document resource. The RFML document resource will be loaded from the classpath. The classpath will first be searched for a serialized resource. If a serialized resource is not found, the classpath will be searched for an RFML source file.
        Parameters:
        documentName - The document resource name of the RFML document for the record formats to be referenced. All RFML-related file extensions are assumed to be lowercase (for example, .rfml or .rfml.ser). The resource name can be a package qualified name. For example, "com.myCompany.myPackage.myRfml"
        loader - The ClassLoader that will be used when loading the specified document resource.
        Throws:
        XmlException - when the specified RFML document cannot be found.

      • setValue

        public void setValue(java.lang.String name,
            java.lang.Object value)
              throws XmlException
        Sets the Java object value for the named element.

        If the input value provided is not an instance of the correct Java class for the defined data type, it will be converted to the correct Java class. For example, if an element is defined as "type=int length=2 precision=15", it will automatically be converted to a Java Short object, if the value specified is an instance of Number or String.

        Parameters:
        name - The name of the <data> element in the RFML document.
        value - The Java object value for the named element. The type of Object passed must be the correct type for the element definition or a String that can be converted to the correct type. Null values are not allowed.
        Throws:
        XmlException - If an error occurs while processing RFML.

      • setValue

        public void setValue(java.lang.String name,
            int[] indices,
            java.lang.Object value)
              throws XmlException
        Sets the Java object value for the named element given indices to the data element. If the data element is an array or is an element in a structure array, an index must be specified for each dimension of the data.

        If the input value provided is not an instance of the correct Java class for the defined data type, it will be converted to the correct Java class. For example, if an element is defined as "type=int length=2 precision=15", it will automatically be converted to a Java Short object, if the value specified is an instance of Number or String.

        Parameters:
        name - The name of the <data> element in the RFML document.
        indices - An array of indices for setting the value of an element in an array.
        value - The Java object value for the named element. The type of Object passed must be the correct type for the element definition or a String that can be converted to the correct type. Null values are not allowed.
        Throws:
        XmlException - If an error occurs while processing RFML.

      • setValues

        public void setValues(java.lang.String formatName,
             Record record)
               throws XmlException
        Sets the Java object values for the specified <recordformat> element, based on the values stored in the record object passed into the method.
        For any given field, if the input value provided is not an instance of the correct Java class for the defined data type, it will be converted to the correct Java class. For example, if an element is defined as "type=int length=2 precision=15", it will automatically be converted to a Java Short object, if the value specified is an instance of Number or String. If any field in the Record is null-valued, a warning is issued.
        Note: The following Record datatypes are not supported by this method:
        Parameters:
        formatName - The name of the <recordformat> element in the RFML document.
        record - The record object containing the data.
        Throws:
        XmlException - If an error occurs while processing RFML, or if an encoding specified by the Record is unsupported.

      • setValues

        public void setValues(java.lang.String formatName,
             byte[] values)
               throws XmlException
        Sets the data represented by the specified <recordformat> element.
        Parameters:
        formatName - The name of the <recordformat> element in the RFML document.
        values - The byte values for all the fields in the the named element. The length of the byte array must exactly match the length of data required, otherwise an XmlException is thrown.
        Throws:
        XmlException - If an error occurs while processing RFML.

      • toByteArray

        public byte[] toByteArray(java.lang.String formatName)
                   throws XmlException
        Returns the data contained by the specified <recordformat> element, as a byte array.
        Parameters:
        formatName - The name of the <recordformat> element in the RFML document.
        Returns:
        The data contained by the record.
        Throws:
        XmlException

      • toRecord

        public Record toRecord(java.lang.String formatName)
                throws XmlException
        Returns a Record object with the same structure and data as the specified <recordformat> element. Before this method is called, all <data> elements must either have their values set, or have 'init' values.
        Note: When the Record is created, the 'count' attribute of <data> elements is disregarded.
        Parameters:
        formatName - The name of the <recordformat> element in the RFML document.
        Returns:
        A Record object containing the same information as the specified <recordformat> element.
        Throws:
        XmlException - If an error occurs while processing RFML.

      • toRecordFormat

        public RecordFormat toRecordFormat(java.lang.String formatName)
                            throws XmlException
        Returns a RecordFormat object with the same structure as the specified <recordformat> element. Note: For <data> elements, the 'count' attribute is disregarded.
        Parameters:
        formatName - The name of the <recordformat> element in the RFML document.
        Returns:
        A RecordFormat object with the same structure as the specified <recordformat> element.
        Throws:
        XmlException

      • toXml

        public void toXml(java.io.OutputStream outputStream)
           throws java.io.IOException,
                  XmlException
        Generates XML (RFML) representing the data contained in this object. Throws an XmlException if this object contains no data.
        Parameters:
        outputStream - The output stream to which to write the text.
        Throws:
        java.io.IOException - If an error occurs while writing the data.
        XmlException - If an error occurs while processing RFML.

      • toXml

        public void toXml(java.io.File file)
           throws java.io.IOException,
                  XmlException
        Generates XML (RFML) representing the data contained in this object. Throws an XmlException if this object contains no data.
        Parameters:
        file - The file to which to write the text.
        Throws:
        java.io.IOException - If an error occurs while writing the data.
        XmlException - If an error occurs while processing RFML.

      • toXml

        public void toXml(java.lang.String fileName)
           throws java.io.IOException,
                  XmlException
        Generates XML (RFML) representing the data contained in this object. Throws an XmlException if this object contains no data.
        Parameters:
        fileName - The pathname of the file to which to write the text.
        Throws:
        java.io.IOException - If an error occurs while writing the data.
        XmlException - If an error occurs while processing RFML.
JTOpen 10.7