org.ipdr.common
Class IPDRDocReader

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

public class IPDRDocReader
extends java.lang.Object

This class deserializes an IPDRDoc from an InputStream according to the compact encoding specification and XML format.

Typical usage involves passing an Input stream, reading the header information, and then extracting individual usage events.

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  CompositeType[] descriptorList_
          The currently encountered descriptors.
protected  IPDRDocEnd docEnd_
          The document end object, after it is read.
 int docType_
          The type of the document (XDR/XML).
protected  IPDRHeader header_
          The header of the document, after it is read.
static int INITIAL_DESCRIPTOR_LIST_SIZE
          The initial descriptor list size.
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 deserialized from this stream.
 java.lang.String ipdrVersion_
          String containing IPDR Version.
 XDRUnMarshaller istreamXDR_
          The input stream the IPDRDoc in XDR is being read from.
 XMLUnMarshaller istreamXML_
          The input stream the IPDRDoc in XML is being read from.
static int READABLE
          Int to represent the DocReader's state when its Readable.
 Schema schema_
          Object of Schema class.
protected  int state_
          The current state of the DocReader.
static int UNREADABLE
          Int to represent the DocReader's state when its Unreadable.
static int XDR
          Int to represent the document type for XDR.
static int XML
          Int to represent the document type for XML.
 
Constructor Summary
IPDRDocReader(java.io.InputStream istream, int docType)
          Creates an object to deserialize the stream.
 
Method Summary
protected  void addDescriptor(RecordDescriptor desc)
          Add the descriptor that was read to the lookup table for future use.
 int getDescriptorCount()
          Method to get the number of descriptors encountered so far.
 IPDRDocEnd getDocEnd()
          Method to get the end of document structure.
 IPDRHeader getHeader()
          Method to get the header of the document.
 int getIpdrCount()
          Method to get the number of usage events encountered so far.
 int getState()
          Method to get the state of this Reader (READABLE / UNREADABLE).
protected  SimpleType mapAttributeToOpenType(AttributeDescriptor desc)
          Method to get the OpenType, given the AttributeDescriptor.
 void readHeader()
          This method is called separately by calling application and it reads header information.
 CompositeData readIPDR()
          Read an IPDR event from the Input Stream.
protected  void readXDRDocEnd(IPDRDocEnd docEnd)
          Mark the end of this IPDR stream, creating an IPDRDocEnd element in the compact IPDRDoc.
 IPDRDocEnd readXMLDocEnd()
          Mark the end of the doc.
 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

istreamXDR_

public XDRUnMarshaller istreamXDR_
The input stream the IPDRDoc in XDR is being read from.


istreamXML_

public XMLUnMarshaller istreamXML_
The input stream the IPDRDoc in XML is being read from.


state_

protected int state_
The current state of the DocReader.


docType_

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


ipdrCount_

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


descriptorCount_

protected int descriptorCount_
The number of different descriptorRecords created.


INITIAL_DESCRIPTOR_LIST_SIZE

public static final int INITIAL_DESCRIPTOR_LIST_SIZE
The initial descriptor list size. It will be grown as necessary to hold encountered descriptors.

See Also:
Constant Field Values

descriptorList_

protected CompositeType[] descriptorList_
The currently encountered descriptors. It is assumed that as descriptor ids are layed down they will be assigned numbers in sequential, increasing order, beginning with 0.

Other assignment policies may be used, but will be less efficient from a storage perspective. In particular the array size will be proporational to max(descriptorId) + 1.

The initial table is set to a size of 10 to avoid resizing.


header_

protected IPDRHeader header_
The header of the document, after it is read.


docEnd_

protected IPDRDocEnd docEnd_
The document end object, after it is read.


schema_

public Schema schema_
Object of Schema class.


ipdrVersion_

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


UNREADABLE

public static final int UNREADABLE
Int to represent the DocReader's state when its Unreadable.

See Also:
Constant Field Values

READABLE

public static final int READABLE
Int to represent the DocReader's state when its Readable.

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

IPDRDocReader

public IPDRDocReader(java.io.InputStream istream,
                     int docType)
              throws java.io.IOException,
                     IPDRException
Creates an object to deserialize the stream. The header is initially read, and then the caller can extract individual usage events.

This object will manage the descriptors transparently so the user only sees a stream of usage events through the readIPDR method.

Parameters:
istream - The Input Stream
docType - The docuemnt type (XML / XDR) (0=XML / 1=XDR)
Throws:
java.io.IOException - when an exception occurs while reading
IPDRException - when a IPDR functionality related exception occurs
Method Detail

setSchema

public void setSchema(Schema s)
               throws java.io.IOException,
                      IPDRException
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 reading
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

readHeader

public void readHeader()
                throws java.io.IOException,
                       IPDRException
This method is called separately by calling application and it reads header information.

Throws:
java.io.IOException
IPDRException

readIPDR

public CompositeData readIPDR()
                       throws java.io.IOException,
                              BadCompositeException,
                              IPDRException
Read an IPDR event from the Input Stream. The class will determine if the DescriptorId 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 read. If the DescriptorId is new, then a RecordDescriptor will first be constructed and then the event will be read.

A null value will be returned when the document end is encountered. Subsequent reads after this will receive an exception.

Returns:
CompositeData object containing the IPDR read.
Throws:
java.io.IOException - when an exception occurs while reading
BadCompositeException - when an exception occurs while constructing Composite Type / Data
IPDRException - when a IPDR functionality related exception occurs

getState

public int getState()
Method to get the state of this Reader (READABLE / UNREADABLE).

Returns:
The state value.

getDescriptorCount

public int getDescriptorCount()
Method to get the number of descriptors encountered so far.

Returns:
The Descriptor Count

getIpdrCount

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

Returns:
The IPDR Count

getHeader

public IPDRHeader getHeader()
Method to get the header of the document.

Returns:
The Document Header.

getDocEnd

public IPDRDocEnd getDocEnd()
Method to get the end of document structure.

Returns:
The Doc End

readXDRDocEnd

protected void readXDRDocEnd(IPDRDocEnd docEnd)
                      throws 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:
docEnd - The DocEnd object
Throws:
IPDRException - when a IPDR functionality related exception occurs

readXMLDocEnd

public IPDRDocEnd readXMLDocEnd()
                         throws java.io.IOException,
                                IPDRException
Mark the end of the doc. Called separatly by calling application.

Returns:
The DocEnd object
Throws:
java.io.IOException - when an exception occurs while reading
IPDRException - when a IPDR functionality related exception occurs

addDescriptor

protected void addDescriptor(RecordDescriptor desc)
                      throws BadCompositeException,
                             IPDRException
Add the descriptor that was read to the lookup table for future use.

Parameters:
desc - The descriptor that was read
Throws:
BadCompositeException - when an exception occurs while constructing Composite Type / Data
IPDRException - when a IPDR functionality related exception occurs

mapAttributeToOpenType

protected SimpleType mapAttributeToOpenType(AttributeDescriptor desc)
                                     throws BadCompositeException
Method to get the OpenType, given the AttributeDescriptor.

Parameters:
desc - The Attribute Descriptor.
Returns:
The corresponding Simple Type
Throws:
BadCompositeException - when the TypeCode is not recognised