org.ipdr.common
Class IPDRDocWriter

java.lang.Object
  extended by org.ipdr.common.IPDRDocWriter

public class IPDRDocWriter
extends java.lang.Object

This class serializes an IPDRDoc to an OutputStream according to the compact encoding specification and XML format.

Typical usage involves specifying the header information in the IPDRDoc when the Writer is constructed and then providing individual usage events, "ipdr's" to be recorded.

The format of the usage events follows the convention defined for OpenMBeans in the Java Management Extension framework: http://java.sun.com/products/JavaManagement. In particular OpenMBeans are described in Chapter X.

The OpenMBean model defines a java data interchange structure called CompositeData. This structure allows an arbitrary data structure to be manipulated by components which have no a priori knowledge of the object structure.


Field Summary
protected  int descriptorCount_
          The number of different descriptorRecords created.
protected  java.util.HashMap descriptorLookup_
          A HashMap keyed by the CompositeType object, which stores the DesciptorId (if any) associated with this type.
 int docType_
          The type of the document (XDR/XML).
protected  IPDRStreamElement elt_
          Cached wrapper for IPDR Stream Element.
static java.util.ArrayList errorList_
          List to store the non-fatal processing errors.
static java.lang.String IPDR_VERSION_3_0
          String to represent the IPDR Version for IPDR v3.0
static java.lang.String IPDR_VERSION_3_1
          String to represent the IPDR Version for IPDR v3.1
static java.lang.String IPDR_VERSION_3_5
          String to represent the IPDR Version for IPDR v3.5
protected  int ipdrCount_
          The count of IPDR's which have been serialized in this stream.
 java.lang.String ipdrVersion_
          String containing IPDR Version.
protected  XDRMarshaller ostreamXDR_
          The output stream the IPDRDoc in XDR is being written to.
protected  XMLMarshaller ostreamXML_
          The output stream the IPDRDoc in XML is being written to.
 Schema schema_
          Object of Schema class.
protected  int state_
          The current state of the DocWriter.
static int UNWRITEABLE
          Int to represent the DocWriter's state when its unwriteable.
static int WRITEABLE
          Int to represent the DocWriter's state when its writeable.
static int XDR
          Int to represent the document type for XDR.
static int XML
          Int to represent the document type for XML.
 
Constructor Summary
IPDRDocWriter(java.io.OutputStream ostream, int docType)
          Constructor.
 
Method Summary
protected  int createDescriptor(CompositeType type)
          Create a descriptor for given Type and register it in the lookup table for later use.
 int getDescriptorCount()
          Method to get the number of Descriptors written so far.
 int getIpdrCount()
          Method to get the number of usage events written so far.
 int getState()
          Method to get the state of this Writer (WRITEABLE / UNWRITEABLE).
protected  int mapOpenTypeToAttributeType(OpenType type)
          Method to get the AttributeType, given the OpenType.
 void setSchema(Schema s)
          This optional method is called by to do validation against schema for a particular IPDRDoc.
 void setVersion(java.lang.String ver)
          This optional method is called when the user chooses not to validation against schema.
 void writeEnd(long endTime)
          Mark the end of this IPDR stream, creating an IPDRDocEnd element in the compact IPDRDoc.
 void writeHeader(java.lang.String ipdrRecorderInfo, long startTime, java.lang.String defaultNSURI, NameSpaceInfo[] otherNameSpaces, java.lang.String[] schemaNameSpaces, java.lang.String[] serviceDefURIs, byte[] docId)
          Writes the header information to the Output Stream.
 void writeIPDR(CompositeData cData)
          Add an IPDR event into the IPDRDoc.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ostreamXDR_

protected XDRMarshaller ostreamXDR_
The output stream the IPDRDoc in XDR is being written to.


ostreamXML_

protected XMLMarshaller ostreamXML_
The output stream the IPDRDoc in XML is being written to.


state_

protected int state_
The current state of the DocWriter.


docType_

public int docType_
The type of the document (XDR/XML).


errorList_

public static java.util.ArrayList errorList_
List to store the non-fatal processing errors.


ipdrCount_

protected int ipdrCount_
The count of IPDR's which have been serialized in this stream. Descriptors are not counted.


descriptorCount_

protected int descriptorCount_
The number of different descriptorRecords created.


descriptorLookup_

protected java.util.HashMap descriptorLookup_
A HashMap keyed by the CompositeType object, which stores the DesciptorId (if any) associated with this type. As CompositeData items are written to the stream. Those sharing the same type will use the same descriptor.


elt_

protected IPDRStreamElement elt_
Cached wrapper for IPDR Stream Element.


schema_

public Schema schema_
Object of Schema class.


ipdrVersion_

public java.lang.String ipdrVersion_
String containing IPDR Version.


UNWRITEABLE

public static final int UNWRITEABLE
Int to represent the DocWriter's state when its unwriteable.

See Also:
Constant Field Values

WRITEABLE

public static final int WRITEABLE
Int to represent the DocWriter's state when its writeable.

See Also:
Constant Field Values

XDR

public static final int XDR
Int to represent the document type for XDR.

See Also:
Constant Field Values

XML

public static final int XML
Int to represent the document type for XML.

See Also:
Constant Field Values

IPDR_VERSION_3_0

public static final java.lang.String IPDR_VERSION_3_0
String to represent the IPDR Version for IPDR v3.0

See Also:
Constant Field Values

IPDR_VERSION_3_1

public static final java.lang.String IPDR_VERSION_3_1
String to represent the IPDR Version for IPDR v3.1

See Also:
Constant Field Values

IPDR_VERSION_3_5

public static final java.lang.String IPDR_VERSION_3_5
String to represent the IPDR Version for IPDR v3.5

See Also:
Constant Field Values
Constructor Detail

IPDRDocWriter

public IPDRDocWriter(java.io.OutputStream ostream,
                     int docType)
              throws IPDRException,
                     java.io.IOException
Constructor. Sets the Document Type to XML or XDR. Initializes the Output Stream based on XML or XDR. Sets the state variable to Unwriteable.

Parameters:
ostream - The output stream to write the IPDR data to
docType - The docuemnt type (XML / XDR) (0=XML / 1=XDR)
Throws:
java.io.IOException - when an exception occurs while writing
IPDRException - when a IPDR functionality related exception occurs
Method Detail

setSchema

public void setSchema(Schema s)
               throws IPDRException,
                      java.io.IOException
This optional method is called by to do validation against schema for a particular IPDRDoc. Bind the schema object passed as input parameter to the IPDRDoc. The schema member variable will be assigned the value of input parameter.

Parameters:
s - Object of Schema class
Throws:
java.io.IOException - when an exception occurs while writing
IPDRException - when a IPDR functionality related exception occurs

setVersion

public void setVersion(java.lang.String ver)
                throws IPDRException
This optional method is called when the user chooses not to validation against schema. This provides the IPDR version (3.0 or 3.5) of the library that would be used.

Parameters:
ver - IPDR Version
Throws:
IPDRException - when a IPDR functionality related exception occurs

writeHeader

public void writeHeader(java.lang.String ipdrRecorderInfo,
                        long startTime,
                        java.lang.String defaultNSURI,
                        NameSpaceInfo[] otherNameSpaces,
                        java.lang.String[] schemaNameSpaces,
                        java.lang.String[] serviceDefURIs,
                        byte[] docId)
                 throws java.io.IOException,
                        IPDRException
Writes the header information to the Output Stream. Sets the state variable to Unwriteable.

Parameters:
ipdrRecorderInfo - Identification information for the producer of this document. Typcially URI, or blank.
startTime - The number of seconds since the Epoch (00:00:00 UTC, January 1, 1970).
defaultNSURI - Identifies the default Namespace associated with this record. Those attribute names which are unqualified will be assumed to be from this namespace.
otherNameSpaces - Identifies additional namespaces from which attributes are derived. This list may be empty.
schemaNameSpaces - Identifies additional namespaces corresponding to serviceDefURIs from which attributes are derived. This list may be empty.
serviceDefURIs - Identifies the set of service definitions from which the records are produced.
docId - The UUID associated with this document.
Throws:
java.io.IOException - when an exception occurs while writing
IPDRException - when a IPDR functionality related exception occurs

writeIPDR

public void writeIPDR(CompositeData cData)
               throws java.io.IOException,
                      BadCompositeException,
                      IPDRException,
                      org.xml.sax.SAXException
Add an IPDR event into the IPDRDoc. The class will determine if the CompositeType associated with this event has already been encountered in this document. If so then a reference will be made to the previously written RecordDescriptor and the event will then be serialized. If the CompositeType is new, then a RecordDescriptor will first be constructed, then serialized and then the event itself will be serialized, referring to the new RecordDescriptor.

Parameters:
cData - Composite Data object containing the IPDR to write
Throws:
java.io.IOException - when an exception occurs while writing
BadCompositeException - when an exception occurs while generating the Composite Type
IPDRException - when a IPDR functionality related exception occurs
org.xml.sax.SAXException - when an exception occurs while parsing the scehma

writeEnd

public void writeEnd(long endTime)
              throws java.io.IOException,
                     IPDRException
Mark the end of this IPDR stream, creating an IPDRDocEnd element in the compact IPDRDoc. This function must only be called once. After calling the IPDRDoc is considered complete. The IPDRDocWriter becomes unwriteable and will throw an IOException if further write attempts are made.

Parameters:
endTime - The end time of the document in milliseconds
Throws:
java.io.IOException - when an exception occurs while writing
IPDRException

getState

public int getState()
Method to get the state of this Writer (WRITEABLE / UNWRITEABLE).

Returns:
The state value

getDescriptorCount

public int getDescriptorCount()
Method to get the number of Descriptors written so far.

Returns:
The Descriptor Count

getIpdrCount

public int getIpdrCount()
Method to get the number of usage events written so far.

Returns:
The IPDR Count

createDescriptor

protected int createDescriptor(CompositeType type)
                        throws java.io.IOException,
                               BadCompositeException,
                               IPDRException
Create a descriptor for given Type and register it in the lookup table for later use.

Parameters:
type - The Composite Type to create the Descriptor from
Returns:
The descriptor number
Throws:
java.io.IOException - when an exception occurs while writing
BadCompositeException - when an exception occurs while generating the Composite Type
IPDRException

mapOpenTypeToAttributeType

protected int mapOpenTypeToAttributeType(OpenType type)
                                  throws BadCompositeException
Method to get the AttributeType, given the OpenType.

Parameters:
type - The Open Type
Returns:
The corresponding Attribute Type
Throws:
BadCompositeException - when the TypeCode is not recognised