com.candle.roma.kxm
Class KxmMessage

java.lang.Object
  |
  +--com.candle.roma.kxm.KxmField
        |
        +--com.candle.roma.kxm.KxmMessage
All Implemented Interfaces:
java.lang.Cloneable

public class KxmMessage
extends KxmField
implements java.lang.Cloneable

This class represents a message with a collection of fields. The KxmMessage class provides an interface to access the whole message: create a KxmMessage object from a data buffer, extract a data buffer from a KxmMessage object, get message information. In addition, it supports the KxmField interfaces, which can be used to get nested fields and type information about message data.

Since:
JDK1.1
See Also:
KxmField, KxmDate, KxmException, KxmRange, KxmMsgCreateOptions, KxmMsgWriteOptions, KxmMsgConvertOptions

Field Summary
static int ANY
          Type of message:
See KxmMessage(String)
See KxmMessage(String,int)
See KxmMessage(String,byte[])
See KxmMessage(String,byte[],int)
See KxmMessage(byte[],int)
See KxmMessage(byte[])
static int BY_MAP
          Determines how the function converts the message
See convert(String,int)
See convert(String)
static int FORMAT_NAME
          Type of message:
See KxmMessage(String)
See KxmMessage(String,int)
See KxmMessage(String,byte[])
See KxmMessage(String,byte[],int)
See KxmMessage(byte[],int)
See KxmMessage(byte[])
static int MDR
          Type of message:
See KxmMessage(String)
See KxmMessage(String,int)
See KxmMessage(String,byte[])
See KxmMessage(String,byte[],int)
See KxmMessage(byte[],int)
See KxmMessage(byte[])
static int STANDALONE
          Type of message:
See KxmMessage(String)
See KxmMessage(String,int)
See KxmMessage(String,byte[])
See KxmMessage(String,byte[],int)
See KxmMessage(byte[],int)
See KxmMessage(byte[])
static int TO_FORMAT
          Determines how the function converts the message
See convert(String,int)
See convert(String)
static int TO_XML
          Determines how the function converts the message
See convert(String,int)
See convert(String)
 
Fields inherited from class com.candle.roma.kxm.KxmField
DTYPE_DATE, DTYPE_DATETIME, DTYPE_GDAY, DTYPE_GMONTH, DTYPE_GMONTHDAY, DTYPE_GYEAR, DTYPE_GYEARMONTH, DTYPE_NONE, DTYPE_TIME, EXACT, FLAG_ARRAY, FLAG_DEFAULT_VALUE, FLAG_GROUP, FLAG_ROOT, FLAG_UNION, FLAG_XMLATTR, FLAG_XMLDOC, FLAG_XMLELEM, GET_SCHEMA_FIELDS, NTYPE_DECIMAL, NTYPE_DOUBLE, NTYPE_FLOAT, NTYPE_INT16, NTYPE_INT32, NTYPE_INT64, NTYPE_INT8, NTYPE_INTEGER, NTYPE_NONE, NTYPE_UINT16, NTYPE_UINT32, NTYPE_UINT64, NTYPE_UINT8, SEARCH, TYPE_BINARY, TYPE_BOOL, TYPE_DATE, TYPE_DURATION, TYPE_GROUP, TYPE_NUMBER, TYPE_QNAME, TYPE_STRING, TYPE_XMLATTR, TYPE_XMLELEM, UNIQUE
 
Constructor Summary
KxmMessage(byte[] data)
          Creates a message object from data parsed as an XML.
KxmMessage(byte[] data, int options)
          Creates a message object from data.
KxmMessage(byte[] data, java.lang.String format, int options, KxmEncoding encoding)
          Creates a message object from data.
KxmMessage(byte[] data, java.lang.String format, KxmMsgCreateOptions options)
          Creates the message from data.
KxmMessage(java.lang.String format)
          Creates an empty message of the specified format.
KxmMessage(java.lang.String format, byte[] data)
          Creates a message based on the MDR format defintion specified by the format parameter.
KxmMessage(java.lang.String format, byte[] data, int options)
          Creates a message object from data.
KxmMessage(java.lang.String format, int options)
          Creates an empty message of the specified format.
KxmMessage(java.lang.String format, KxmMsgCreateOptions options)
          Creates an empty message of the specified format.
 
Method Summary
 java.lang.Object clone()
          Returns a copy of the KxmMessage object.
 KxmMessage convert(java.lang.String format)
          Converts message data from one format to another one.
 KxmMessage convert(java.lang.String format, int options)
          Converts a message buffer from one message format to another one.
 KxmMessage convert(java.lang.String format, KxmMsgConvertOptions options)
          Converts message data from one message format to another one.
 void destroy()
          Forces destruction of the underlying JNI object.
static long getAliveMessagesCount()
           
 java.lang.String getFormatName()
          Returns the Metadata Repository format definition name that this message is based on.
 KxmEncoding getLastEncoding()
          Returns encoding that was in effect for the last call of the following methods:
write()
write(KxmEncoding)
write(KxmMsgWriteOptions)
 java.lang.String getXmlDocName()
          Returns a name of the root XML element.
 java.lang.String toString()
          Returns a string representation of the object.
 byte[] write()
          Extracts message data.
 byte[] write(KxmEncoding encoding)
          Extracts message data.
 byte[] write(KxmMsgWriteOptions options)
          Extracts message data.
 
Methods inherited from class com.candle.roma.kxm.KxmField
applyFormat, applyFormat, at, declareNs, findField, findField, getArrayLen, getArrayLenRange, getBool, getByteArray, getCharacterData, getDate, getDateType, getDefault, getDouble, getDuration, getField, getField, getField, getField, getFlags, getHandle, getLocalPart, getLong, getName, getNsPrefix, getNsUri, getNumericType, getNumOfFields, getNumOfFields, getObject, getParent, getQName, getString, getType, getValueLenRange, isArray, isDefaultValue, isEmpty, isGroup, isInvalid, isNil, isRoot, loadMessageApi, set, set, set, set, set, set, set, set, set, setArrayLen, setBool, setCharacterData, setEmpty, setNil
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

STANDALONE

public static final int STANDALONE
Type of message:
See KxmMessage(String)
See KxmMessage(String,int)
See KxmMessage(String,byte[])
See KxmMessage(String,byte[],int)
See KxmMessage(byte[],int)
See KxmMessage(byte[])

MDR

public static final int MDR
Type of message:
See KxmMessage(String)
See KxmMessage(String,int)
See KxmMessage(String,byte[])
See KxmMessage(String,byte[],int)
See KxmMessage(byte[],int)
See KxmMessage(byte[])

ANY

public static final int ANY
Type of message:
See KxmMessage(String)
See KxmMessage(String,int)
See KxmMessage(String,byte[])
See KxmMessage(String,byte[],int)
See KxmMessage(byte[],int)
See KxmMessage(byte[])

FORMAT_NAME

public static final int FORMAT_NAME
Type of message:
See KxmMessage(String)
See KxmMessage(String,int)
See KxmMessage(String,byte[])
See KxmMessage(String,byte[],int)
See KxmMessage(byte[],int)
See KxmMessage(byte[])

TO_XML

public static final int TO_XML
Determines how the function converts the message
See convert(String,int)
See convert(String)

TO_FORMAT

public static final int TO_FORMAT
Determines how the function converts the message
See convert(String,int)
See convert(String)

BY_MAP

public static final int BY_MAP
Determines how the function converts the message
See convert(String,int)
See convert(String)
Constructor Detail

KxmMessage

public KxmMessage(java.lang.String format)
           throws KxmException
Creates an empty message of the specified format. Creates a message based on MDR format defintion specified by the format parameter. If the MDR does not contain the format definition then XML-Auto-Recognize logic takes place: the method preparses message data as an XML and determines name of the root XML element. If preparsing succeeds, then method attempts to load the MDR format definition with the name matching the root XML element. If the format definition is not found again, then the method fails.
Parameters:
format - Name of the message format.
Throws:
KxmException - will be thrown on an error.

KxmMessage

public KxmMessage(java.lang.String format,
                  int options)
           throws KxmException
Creates an empty message of the specified format.
Parameters:
format - Name of the message format. An application specifies either the format name of the message or the name of the XML document, depending on the type parameter provided.
type - Specifies the type of message to be created. It must be on of the following constants:
  • KxmMessage.MDR Creates message based on MDR format defintion specified by the formatName parameter. If MDR does not contain format definition then function fails.
  • KxmMessage.STANDALONE Creates XML message not described in the MDR. The formatNamae specifies name of the root element.
  • KxmMessage.ANY The same as MDR, but if format definition is not present then creates XML message not described in the MDR, same as STANDALONE does.
  • KxmMessage.FORMAT_NAME Creates message based on MDR format defintion specified by the formatName parameter. If MDR does not contain format definition then method fails.
Throws:
KxmException - will be thrown on an error.

KxmMessage

public KxmMessage(java.lang.String format,
                  byte[] data)
           throws KxmException
Creates a message based on the MDR format defintion specified by the format parameter. If MDR does not contain the format definition, then XML-Auto-Recognize logic takes place: the method preparses message data as an XML and determines the name of the root XML element. If preparsing succeeds, then the method attempts to load the MDR format definition with the name matching the root XML element. If the format definition is not found again, then the method fails.
Parameters:
format - Name of the message format.
data - Message data.
Throws:
KxmException - will be thrown on an error.

KxmMessage

public KxmMessage(java.lang.String format,
                  byte[] data,
                  int options)
           throws KxmException
Creates a message object from data.
Parameters:
format - Name of the message format.
data - Message data.
opt - Specifies type of message to be created. It must be on of the following constants:
KxmMessage.MDRCreates message based on MDR format defintion specified by the format parameter. If MDR does not contain format definition then XML-Auto-Recognize logic takes place: the method preparses message as an XML and determines name of the root XML element. If preparsing succeeds then method tries to load the MDR format definition with name matching the root XML element. If format definition is not found again then method fails.
KxmMessage.STANDALONENot allowed parameter, method fails.
KxmMessage.ANYThe same as MDR, but if XML-Auto-Recognize logic fails then the method parses data as an XML. KxmMessage.FORMAT_NAMECreates message based on MDR format defintion specified by the formatName parameter. If MDR does not contain format definition then method fails.
Throws:
KxmException - will be thrown on an error.

KxmMessage

public KxmMessage(byte[] data)
           throws KxmException
Creates a message object from data parsed as an XML.
Parameters:
data - Message data
Throws:
KxmException - will be thrown on an error.

KxmMessage

public KxmMessage(byte[] data,
                  int options)
           throws KxmException
Creates a message object from data.
Parameters:
data - Message data.
options - Specifies type of message to be created. It must be one of the following constants:
KxmMessage.MDRCreates message based on MDR format defintion specified by the formatName parameter. If MDR does not contain format definition then XML-Auto-Recognize logic takes place: the method preparses message as an XML and determines name of the root XML element. If preparsing succeeds then method tries to load the MDR format definition with name matching the root XML element. If format definition is not found again then method fails.
KxmMessage.STANDALONEParses data as an XML.
KxmMessage.ANYThe same as MDR, but if XML-Auto-Recognize logic fails then the method parses data as an XML.
KxmMessage.FORMAT_NAME Not allowed parameter, method fails.
Throws:
KxmException - will be thrown on an error.

KxmMessage

public KxmMessage(byte[] data,
                  java.lang.String format,
                  int options,
                  KxmEncoding encoding)
           throws KxmException
Creates a message object from data.
Parameters:
data - Message data.
format - Name of the message format, can be null.
options - Specifies type of message to be created. It must be one of the following constants:
KxmMessage.MDRCreates message based on MDR format defintion specified by the format parameter. If MDR does not contain format definition or the format parameter is null, then XML-Auto-Recognize logic takes place: the method preparses message as an XML and determines name of the root XML element. If preparsing succeeds, then method tries to load the MDR format definition with name matching the root XML element. If format definition is not found again, then method fails.
KxmMessage.STANDALONEThe format paramter should be null. Parses data as an XML message.
KxmMessage.ANY The same as MDR, but if XML-Auto-Recognize logic fails, then the method parses data as an XML message. KxmMessage.FORMAT_NAMECreates message based on the MDR format defintion specified by the format parameter. If MDR does not contain format definition or format paramter is null, then method fails.
encoding - Encoding, can be null. This parameter is used as a suggestion of the encoding for the XML message. If recognized encoding of the input message does not match the this parameter, then parameter is ignored. For the raw messages the only supported encodings are "NATIVE" and "UTF-16".
Throws:
KxmException - will be thrown on an error.

KxmMessage

public KxmMessage(java.lang.String format,
                  KxmMsgCreateOptions options)
           throws KxmException
Creates an empty message of the specified format.
Parameters:
format - Name of the message format.
option - Message creation options.
Throws:
KxmException - will be thrown on an error.
See Also:
KxmMsgCreateOptions

KxmMessage

public KxmMessage(byte[] data,
                  java.lang.String format,
                  KxmMsgCreateOptions options)
           throws KxmException
Creates the message from data.
Parameters:
data - Message data.
format - Name of the message format, can be null.
options - Message creation options.
Throws:
KxmException - will be thrown on an error.
See Also:
KxmMsgCreateOptions
Method Detail

getFormatName

public java.lang.String getFormatName()
                               throws KxmException
Returns the Metadata Repository format definition name that this message is based on. Returns an empty string if the message is a standalone XML.
Throws:
KxmException - will be thrown on an error.

getXmlDocName

public java.lang.String getXmlDocName()
                               throws KxmException
Returns a name of the root XML element. Returns an empty string if the message format is not XML.
Throws:
KxmException - will be thrown on an error.

convert

public KxmMessage convert(java.lang.String format,
                          int options)
                   throws KxmException
Converts a message buffer from one message format to another one.
Parameters:
format - Depending from options, it is either:
  • name of the target format (TO_FORMAT)
  • name of the root element of the resulting XML document (TO_XML)
  • name of the conversion map (BY_MAP)
options - Conversion options. This parameter determines how the function converts the message:
  • KxmMessage.TO_XMLThe function converts the message into a standalone XML document. The name parameter should specify the root element name for the target XML document. This option does not use any conversion maps.
  • KxmMessage.TO_FORMATThe function converts the message into the format specified by the name and defined in the Metadata Repository. This option first searches conversion map that can convert from the source to the target format. The map is only searched in the same namespace where source format resides. If the map is not found then the format is converted based on default conversion rules.
  • KxmMessage.BY_MAPThe function converts the message by the map specified by the name and defined in the Metadata Repository. The message can not be standalone and should have the same format as the source format of the map.
Returns:
Result of the conversion.
Throws:
KxmException - will be thrown on an error.

convert

public KxmMessage convert(java.lang.String format)
                   throws KxmException
Converts message data from one format to another one. The function converts the message into the format specified by the name and defined in the Metadata Repository. This option first searches conversion map that can convert from the source to the target format. The map is only searched in the same namespace where source format resides. If the map is not found, then the format is converted based on the default conversion rules.
Parameters:
format - Name of the target format.
Returns:
Result of the conversion.
Throws:
KxmException - will be thrown on an error.

convert

public KxmMessage convert(java.lang.String format,
                          KxmMsgConvertOptions options)
                   throws KxmException
Converts message data from one message format to another one.
Parameters:
format - Name of the target format.
options - Message conversion options.
Returns:
Result of the conversion.
Throws:
KxmException - will be thrown on an error.
See Also:
KxmMsgConvertOptions

write

public byte[] write()
             throws KxmException
Extracts message data.
Throws:
KxmException - will be thrown on an error.

write

public byte[] write(KxmEncoding encoding)
             throws KxmException
Extracts message data.
Parameters:
encoding - Specifies in which encoding message should be written. The only allowed encoding for the raw messages is "NATIVE". For the XML messages any supported encoding is allowed. For the XML messages "NATIVE" means "UTF-8" on the ASCII platforms and current encoding of the platform on the non-ASCII platforms. If the encoding parameter is null, then this method is equivalent to the write() method.
Throws:
KxmException - will be thrown on an error.

write

public byte[] write(KxmMsgWriteOptions options)
             throws KxmException
Extracts message data.
Parameters:
options - Message extraction options. If the options parameter is null, then this method is equivalent to the write() method.
Throws:
KxmException - will be thrown on an error.

getLastEncoding

public KxmEncoding getLastEncoding()
                            throws KxmException
Returns encoding that was in effect for the last call of the following methods:
write()
write(KxmEncoding)
write(KxmMsgWriteOptions)
Throws:
KxmException - is thrown if there was no write call.

destroy

public void destroy()
             throws KxmException
Forces destruction of the underlying JNI object. The KxmMessage is a wrapper for the C++ message object. This C++ object uses much more memory than the Java object. The Java Garbage Collector is unaware of the memory size occupied by the JNI implementation of an Java object, so JVM can accumulate a lot of unfinalized message objects. These objects occupy a small amount of memory visible to the GC, but the amount of memory used by their JNI code could be huge. To prevent memory exhaust, call this method to destroy the JNI message object when you have finished with a message processing. Note, this method invalidates the Java message object, thus invokation of any message method will raise the KxmException with the KXMRC_INVALID_MESSAGE error code.

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
Returns a copy of the KxmMessage object.

toString

public java.lang.String toString()
Returns a string representation of the object.
Overrides:
toString in class KxmField

getAliveMessagesCount

public static long getAliveMessagesCount()
Returns:
Number of messages which are not destroyed yet.