Package com.kristensoft.kdc

Class AgentSerializer

java.lang.Object

com.kristensoft.kdc.AgentSerializer

public class AgentSerializer
extends Object

Serializes and deserializes KDC Agent and Reply objects for transmission between communication endpoints.

This serializer manages KDC packet creation and processing, object serialization, compression, encryption, CRC checking, class whitelisting, protocol versioning, and send and receive buffer limits.

Serialization behavior is initially configured from Parameters. Selected settings, including compression, encryption, CRC checking, and serialization format, may be changed through this serializer.

When changing serialization settings at runtime, communicating endpoints must use compatible settings to successfully exchange data.

The KDC wire format is subject to change between versions. Serialized agent or reply bytes should not be treated as a persistent storage format and are not guaranteed to be compatible with subsequent versions of KDC or its serialization implementation.

Author:

Charles B. Kozoyed

Constructor Summary

Constructors

Constructor	Description
AgentSerializer(Parameters parameters)	Constructs an agent serializer using the specified KDC configuration.

Method Summary

Modifier and Type	Method	Description
void	addToWhiteList(String className)	Adds a class or package name to the whitelist of classes permitted during deserialization.
Agent	deserialize(byte[] data)	Deserializes a KDC packet contained in the specified byte array into an agent.
Agent	deserialize(byte[] bytes, int offset, int length)	Deserializes a KDC packet contained within the specified portion of a byte array into an agent.
Reply	deserializeReply(byte[] bytes, Parameters parameters)	Deserializes a KDC packet into a reply.
com.kristensoft.ko.EncryptionKey	getEncryptionKey()	Returns the encryption key currently configured for this serializer.
com.kristensoft.ko.KristenObjectsSerializer.SerializationFormat	getFormat()	Returns the serialization format currently configured for this serializer.
boolean	isCompressed()	Determines whether compression is enabled for this serializer.
boolean	isCrcCheck()	Determines whether CRC checking is enabled for this serializer.
void	removeFromWhitelist(String className)	Removes a class or package name from the whitelist of classes permitted during deserialization.
byte[]	serialize(Agent agent)	Serializes the specified agent into a KDC packet for transmission.
void	setCompressed(boolean compressed)	Enables or disables compression for this serializer.
void	setCrcCheck(boolean crcCheck)	Enables or disables CRC checking for serialized packets.
void	setEncryptionKey(com.kristensoft.ko.EncryptionKey encryptionKey)	Sets the encryption key used by this serializer.
void	setFormat(com.kristensoft.ko.KristenObjectsSerializer.SerializationFormat format)	Sets the serialization format used by this serializer.

Methods inherited from class java.lang.Object

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

Constructor Detail

AgentSerializer

public AgentSerializer(Parameters parameters)

Constructs an agent serializer using the specified KDC configuration.

The supplied parameters determine the protocol version, send and receive buffer limits, and initial class whitelist used by this serializer.

Parameters:

parameters - the KDC parameters used to configure this serializer

Throws:

IllegalArgumentException - if parameters is null

Method Detail

addToWhiteList

public void addToWhiteList(String className)

Adds a class or package name to the whitelist of classes permitted during deserialization.

Classes that may be instantiated as part of a received agent's object graph must be permitted by the serializer's whitelist.

To whitelist a package, specify the fully qualified package name ending with a period (.).

Parameters:

className - the fully qualified class name or package name to add to the whitelist

Throws:

IllegalArgumentException - if className is null or blank

removeFromWhitelist

public void removeFromWhitelist(String className)

Removes a class or package name from the whitelist of classes permitted during deserialization.

When removing a package, specify the fully qualified package name ending with a period (.), matching the entry used when the package was added to the whitelist.

Parameters:

className - the fully qualified class name or package name to remove from the whitelist

Throws:

IllegalArgumentException - if className is null or blank

setEncryptionKey

public void setEncryptionKey(com.kristensoft.ko.EncryptionKey encryptionKey)

Sets the encryption key used by this serializer.

Setting a non-null encryption key enables encryption. Setting the encryption key to null disables encryption.

Communicating endpoints must use compatible encryption settings and keys to successfully exchange encrypted data.

Parameters:

encryptionKey - the encryption key to use, or null to disable encryption

setCompressed

public void setCompressed(boolean compressed)

Enables or disables compression for this serializer.

When enabled, serialized data is compressed before transmission. When disabled, serialized data is transmitted without compression.

Communicating endpoints must use compatible compression settings to successfully exchange data.

Parameters:

compressed - true to enable compression; false to disable compression

isCrcCheck

public boolean isCrcCheck()

Determines whether CRC checking is enabled for this serializer.

Returns:

true if CRC checking is enabled; false otherwise

setCrcCheck

public void setCrcCheck(boolean crcCheck)

Enables or disables CRC checking for serialized packets.

When enabled, a CRC value is included with serialized packets and may be used to detect data corruption during transmission. CRC checking is disabled by default.

Parameters:

crcCheck - true to enable CRC checking; false to disable CRC checking

isCompressed

public boolean isCompressed()

Determines whether compression is enabled for this serializer.

Returns:

true if compression is enabled; false otherwise

getEncryptionKey

public com.kristensoft.ko.EncryptionKey getEncryptionKey()

Returns the encryption key currently configured for this serializer.

Returns:

the configured encryption key, or null if encryption is disabled

setFormat

public void setFormat(com.kristensoft.ko.KristenObjectsSerializer.SerializationFormat format)

Sets the serialization format used by this serializer.

Communicating endpoints must use compatible serialization formats to successfully exchange data.

Parameters:

format - the serialization format to use

getFormat

public com.kristensoft.ko.KristenObjectsSerializer.SerializationFormat getFormat()

Returns the serialization format currently configured for this serializer.

Returns:

the configured serialization format

serialize

public byte[] serialize(Agent agent)
                 throws IOException,
                        KristenCommsException

Serializes the specified agent into a KDC packet for transmission.

The agent is serialized according to the current serialization, compression, encryption, CRC, and protocol version settings of this serializer.

Parameters:

agent - the agent to serialize

Returns:

the serialized KDC packet

Throws:

IllegalArgumentException - if agent is null

IOException - if an I/O error occurs while creating the packet

KristenCommsException - if the agent cannot be serialized into a valid KDC packet

deserialize

public Agent deserialize(byte[] bytes,
                         int offset,
                         int length)
                  throws KristenCommsException,
                         com.kristensoft.ko.KristenObjectsException,
                         IOException,
                         ClassNotFoundException

Deserializes a KDC packet contained within the specified portion of a byte array into an agent.

The packet is validated according to the configured protocol version and receive buffer limit. The packet's class must be permitted for deserialization and must be assignable to Agent. Compression and encryption settings must be compatible with those of this serializer.

Parameters:

bytes - the byte array containing the serialized KDC packet

offset - the starting offset of the packet within the byte array

length - the number of bytes to deserialize

Returns:

the deserialized agent

Throws:

IllegalArgumentException - if bytes is null

KristenCommsException - if the packet is invalid, exceeds the receive buffer limit, contains an invalid agent type, or is incompatible with the serializer configuration

com.kristensoft.ko.KristenObjectsException - if object deserialization fails

IOException - if an I/O error occurs while reading the packet

ClassNotFoundException - if the agent class cannot be found

deserialize

public Agent deserialize(byte[] data)
                  throws IOException,
                         ClassNotFoundException,
                         com.kristensoft.ko.KristenObjectsException,
                         KristenCommsException

Deserializes a KDC packet contained in the specified byte array into an agent.

This method deserializes the entire byte array.

Parameters:

data - the byte array containing the serialized KDC packet

Returns:

the deserialized agent

Throws:

IllegalArgumentException - if data is null

IOException - if an I/O error occurs while reading the packet

ClassNotFoundException - if the agent class cannot be found

com.kristensoft.ko.KristenObjectsException - if object deserialization fails

KristenCommsException - if the packet is invalid or cannot be deserialized using the current serializer configuration

deserializeReply

public Reply deserializeReply(byte[] bytes,
                              Parameters parameters)
                       throws ClassNotFoundException,
                              IOException,
                              com.kristensoft.ko.KristenObjectsException,
                              KristenCommsException

Deserializes a KDC packet into a reply.

The packet's class must be permitted for deserialization and must be assignable to Reply. The protocol version specified by the supplied parameters is used to determine the packet format.

Parameters:

bytes - the byte array containing the serialized KDC reply packet

parameters - the KDC parameters containing the protocol version to use

Returns:

the deserialized reply

Throws:

IllegalArgumentException - if bytes or parameters is null

ClassNotFoundException - if the reply class cannot be found

IOException - if an I/O error occurs while reading the packet

com.kristensoft.ko.KristenObjectsException - if object deserialization fails

KristenCommsException - if the packet is invalid, does not contain a reply, or cannot be deserialized