net.sf.xbus.protocol.records
Class RecordTypeParser

java.lang.Object
  extended by net.sf.xbus.protocol.records.RecordTypeParser

public class RecordTypeParser
extends java.lang.Object

The class RecordTypeParser implements parsing records from a string or a list of byte arrays.

The parsed structure is described by a xml file - in particular the contained record types, their order within the string and how to identify them during parsing. Such describing files are of document type InterfaceSpec declared in "InterfaceSpec.dtd".

The parsing result is a DOM tree with the following structure:

<+ InterfaceName +>

<+ HeaderName +> <+ FieldName +>+ FieldValue +</+ FieldName +>
...
</+ HeaderName +>
<Records> <RecordGroup> <+ RecordType +> <+ FieldName +>+ FieldValue +</+ FieldName +>
...
</+ RecordType +>
...
</RecordGroup>
...
</Records>
<+ TrailerName +> <+ FieldName +>+ FieldValue +</+ FieldName +>
...
</+ TrailerName +>
</+ InterfaceName +>

Header and trailer are optional.
The <RecordGroup> structure is only used if records of different types are grouped together in the string (RecordOrder=Structured for the <Lines> specification in the structure description). Otherwise records are listed immediately below the <Records> level.

There is no DTD for the parsing result since the used tags depend on the document structure of the parsed file (tags indicated by +'s above). But it can be derived from the structure description taking the name attributes for interface type, header, record types, fields and trailer as tags.

The "ordinary" working mode is parsing records from a string. But due to special problems with some character encoding and line breaks within record fields, byte-array-oriented parsing is available, too. In this case each record is stored in its own byte array.

Author:
Stephan Dwel

Field Summary
protected  boolean checkingActivated
          Is the checking of the structrure description activated?
protected  java.lang.String contentType
          contentType contains the name for the parsed structure as it is derived from a interfaceStructure.
protected  org.w3c.dom.Node groupsSpec
          groupsSpec is a shortcut into the interfaceStructurefor the specification section of field groups.
protected  org.w3c.dom.Element headerSpec
          headerSpec is a shortcut into the interfaceStructurefor the file/string header.
protected  int interfaceContentClass
          The RecordTypeManipulator is able to treat interface file contents as strings or as byte array lists.
protected  int interfaceContentLength
          Length of interface file in sense of
(a) characters if the content is represented as string
(b) bytes if the content is represented as byte array list
protected  org.w3c.dom.Document interfaceStructure
          interfaceStructure holds the structure description used for parsing/serializing.
protected  org.w3c.dom.Element linesSpec
          linesSpec is a shortcut into the interfaceStructurefor the lines specification.
protected  java.lang.String recIdentMethod
          recIdentMethod indicates how the records with the parsed string are identified during parsing.
protected  java.lang.String recOrder
          recOrder determines in which order the differnt record types occurr in the parsed string.
protected  org.w3c.dom.Node recordTypesSpec
          recordTypesSpec is a shortcut into the interfaceStructurefor the specification section of record types.
protected  java.lang.String sourceType
          sourceType contains the name for the parsed structure as it is derived from a RecordTypeMessage.
protected  org.w3c.dom.Element trailerSpec
          trailerSpec is a shortcut into the interfaceStructurefor the file/string trailer.
 
Method Summary
protected  java.lang.String extractSubString(byte[] array, int pos, int length)
          extractSubString extracts a field value as string from a specific position in a byte array.
protected  ByteArrayConverter getByteArrayConverter()
          getByteArrayConverter retrieves a byte array converter object which is convenient for the interface from which the records are to parse.
protected  int getFieldPos(org.w3c.dom.Element fieldSpec, org.w3c.dom.Node parentSpec)
          getFieldPos determines the position of a field within the surrounding record type - including header and trailer.
static RecordTypeParser getInstance(java.lang.String sourceType, int interfaceContentClass)
          getInstance() retrieves the an instance of RecordTypeParser.
 int getInterfaceContentClass()
          getInterfaceContentClass retrieves the mode (string or byte array list) in which the RecordTypeManipulator is working in.
protected  java.lang.String getInterfaceDescription(java.lang.String system)
          getInterfaceDescription extracts the name of the interface description file.
protected  org.w3c.dom.Element getRecordTypeById(java.lang.String searchedId)
          getRecordTypeByID retrieves the record type declaration within the lines section by the type identifier.
protected  int getRecordTypePositionInLines(org.w3c.dom.Element recordType)
          getRecordTypePositionInLines retrieves the position of a record type in the lines section.
protected  org.w3c.dom.Node getRecordTypeSpec(java.lang.String recordType)
          getRecordTypeSpec retrieves the record type specification from the record types section to a record type name.
 java.lang.String getSourceType()
          getSourceType retrieves the name for the parsed structure as it is derived from a RecordTypeMessage.
protected  java.lang.String getTypeIdentifier(java.lang.String idPosString, org.w3c.dom.Node recordTypeSpec)
          getTypeIdentifier retrieves the type identifier field.
 void initialize(java.lang.String system, int ifContentClass, javax.xml.parsers.DocumentBuilder builder)
          initialize sets the name for the parsed structure and the structure description used for parsing/serializing.
 void parse(java.lang.Object interfaceContent, org.w3c.dom.Document resultDoc)
          parse parses a string due to the record type definition.
 int parseSingleRecord(byte[] inRecord, org.w3c.dom.Document doc, org.w3c.dom.Element[] recordType, int recordCount)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

sourceType

protected java.lang.String sourceType
sourceType contains the name for the parsed structure as it is derived from a RecordTypeMessage. RecordTypeManipulator does not garuantee the consistency of sourceType,contentTypeand interfaceStructure.


contentType

protected java.lang.String contentType
contentType contains the name for the parsed structure as it is derived from a interfaceStructure. RecordTypeManipulator does not garuantee the consistency of contentType and sourceType


interfaceStructure

protected org.w3c.dom.Document interfaceStructure
interfaceStructure holds the structure description used for parsing/serializing. But RecordTypeManipulator does not load the structure description itself from a file nor does it garuantee the consistency of sourceTypewith interfaceStructure.


headerSpec

protected org.w3c.dom.Element headerSpec
headerSpec is a shortcut into the interfaceStructurefor the file/string header.


linesSpec

protected org.w3c.dom.Element linesSpec
linesSpec is a shortcut into the interfaceStructurefor the lines specification.


recordTypesSpec

protected org.w3c.dom.Node recordTypesSpec
recordTypesSpec is a shortcut into the interfaceStructurefor the specification section of record types.


trailerSpec

protected org.w3c.dom.Element trailerSpec
trailerSpec is a shortcut into the interfaceStructurefor the file/string trailer.


groupsSpec

protected org.w3c.dom.Node groupsSpec
groupsSpec is a shortcut into the interfaceStructurefor the specification section of field groups.


recIdentMethod

protected java.lang.String recIdentMethod
recIdentMethod indicates how the records with the parsed string are identified during parsing. Possible values are:


recOrder

protected java.lang.String recOrder
recOrder determines in which order the differnt record types occurr in the parsed string. Possible values are:


checkingActivated

protected boolean checkingActivated
Is the checking of the structrure description activated?


interfaceContentClass

protected int interfaceContentClass
The RecordTypeManipulator is able to treat interface file contents as strings or as byte array lists. interfaceContentClass contains the information which of these media is used.


interfaceContentLength

protected int interfaceContentLength
Length of interface file in sense of
(a) characters if the content is represented as string
(b) bytes if the content is represented as byte array list

Method Detail

getInstance

public static RecordTypeParser getInstance(java.lang.String sourceType,
                                           int interfaceContentClass)
                                    throws XException
getInstance() retrieves the an instance of RecordTypeParser.

Parameters:
sourceType - the name for the parsed structure as it is derived from a RecordTypeMessage
interfaceContentClass - Working mode: sting or byte array list
Throws:
XException - in case of missing sourceType

getByteArrayConverter

protected ByteArrayConverter getByteArrayConverter()
                                            throws XException
getByteArrayConverter retrieves a byte array converter object which is convenient for the interface from which the records are to parse.

Returns:
an appropriate converter object
Throws:
XException

parse

public void parse(java.lang.Object interfaceContent,
                  org.w3c.dom.Document resultDoc)
           throws XException
parse parses a string due to the record type definition.

Parameters:
interfaceContent - the string to parse
resultDoc - The parsing result - an empty DOM tree which will be filled.
Throws:
XException - in case that the interface structure description is not loaded or in case of an unexpected value or end of string/byte array/byte array list

parseSingleRecord

public int parseSingleRecord(byte[] inRecord,
                             org.w3c.dom.Document doc,
                             org.w3c.dom.Element[] recordType,
                             int recordCount)
                      throws XException
Parameters:
inRecord -
doc -
Throws:
XException

extractSubString

protected java.lang.String extractSubString(byte[] array,
                                            int pos,
                                            int length)
                                     throws XException
extractSubString extracts a field value as string from a specific position in a byte array. The extraction is done in two steps:
  1. Extraction of bytes due to position and length
  2. Conversion to string by the preloaded byte array converter

Parameters:
array - the byte array to extract the field value from
pos - the field starting position in the array (byte count)
length - the field length (byte count)
Returns:
the field value converted to a string
Throws:
XException - in case of unpossible pos or length values

getSourceType

public java.lang.String getSourceType()
getSourceType retrieves the name for the parsed structure as it is derived from a RecordTypeMessage. RecordTypeManipulator does not garuantee the consistency of sourceType,contentTypeand interfaceStructure.


getInterfaceContentClass

public int getInterfaceContentClass()
getInterfaceContentClass retrieves the mode (string or byte array list) in which the RecordTypeManipulator is working in.


getInterfaceDescription

protected java.lang.String getInterfaceDescription(java.lang.String system)
                                            throws XException
getInterfaceDescription extracts the name of the interface description file.

Parameters:
system - the origin of the message
Returns:
name of the interface description file
Throws:
XException - in case that the interface file name can not be retrieved

initialize

public void initialize(java.lang.String system,
                       int ifContentClass,
                       javax.xml.parsers.DocumentBuilder builder)
                throws XException
initialize sets the name for the parsed structure and the structure description used for parsing/serializing. The structure description is checked if this option is activated in the configuration. RecordTypeManipulator does not load the structure description itself from a file nor does it garuantee the consistency of sourceTypewith interfaceStructure.

Parameters:
system - the name for the parsed structure as it is derived from a RecordTypeMessage
ifContentClass - the mode (string or byte array list) in which the RecordTypeManipulator is working in
builder - ???
Throws:
XException - in case of an illegal structure description. In this case the description is not set!

getRecordTypePositionInLines

protected int getRecordTypePositionInLines(org.w3c.dom.Element recordType)
                                    throws XException
getRecordTypePositionInLines retrieves the position of a record type in the lines section.

Parameters:
recordType - as node in the lines section
Returns:
the position of the record type in the lines section (starting at 0) - relative to the record group if recOrder =="Structured"
Throws:
XException - in case that the record type cannot be found

getRecordTypeById

protected org.w3c.dom.Element getRecordTypeById(java.lang.String searchedId)
                                         throws XException
getRecordTypeByID retrieves the record type declaration within the lines section by the type identifier.

Parameters:
searchedId - the type identifier
Returns:
the record type declaration node in the lines section as as Element
Throws:
XException - in case that the record type cannot be found

getRecordTypeSpec

protected org.w3c.dom.Node getRecordTypeSpec(java.lang.String recordType)
                                      throws XException
getRecordTypeSpec retrieves the record type specification from the record types section to a record type name.

Parameters:
recordType - the record type name
Returns:
the record type specification as nodein the interface structure description
Throws:
XException - in case that the record type specification cannot be found

getFieldPos

protected int getFieldPos(org.w3c.dom.Element fieldSpec,
                          org.w3c.dom.Node parentSpec)
                   throws XException
getFieldPos determines the position of a field within the surrounding record type - including header and trailer.

Parameters:
fieldSpec - the field as elementnode
parentSpec - the specification of the surrounding record type
Returns:
the field position within the record type
Throws:
XException - in case of problems with the description file

getTypeIdentifier

protected java.lang.String getTypeIdentifier(java.lang.String idPosString,
                                             org.w3c.dom.Node recordTypeSpec)
                                      throws XException
getTypeIdentifier retrieves the type identifier field.

Parameters:
idPosString - the identifier position in the record line - in sense of char counting if the interface contant is treated as string; in sense of byte counting if a byte array list is used instead
recordTypeSpec - the record type specification to search in
Returns:
the name of the type identifier field - null if it could not be found
Throws:
XException - in case of problems with the description file or the identifier position