javax.slee.resource

Interface Marshaler

public interface Marshaler

The Marshaler interface defines methods that allow a resource adaptor to control the serialization of event objects and activity handles. Serialization of these objects may be required, for example, in a clustered environment where events and/or activities are replicated.

A resource adaptor is not required to implement the Marshaler interface. A resource adaptor that does not provide such an implementation is not permitted to use the ActivityFlags.SLEE_MAY_MARSHAL flag when starting activities, or the EventFlags.SLEE_MAY_MARSHAL flag when firing events.

Since:

SLEE 1.1

Method Summary

Methods

Modifier and Type	Method and Description
int	getEstimatedEventSize(FireableEventType eventType, Object event) Get an estimate of the size (in bytes) of the marshaled form of the specified event or event type.
int	getEstimatedHandleSize(ActivityHandle handle) Get an estimate of the size (in bytes) of the marshaled form of an activity handle.
ByteBuffer	getEventBuffer(FireableEventType eventType, Object event) Get a buffer containing an already marshaled for of the specified event, if such a buffer exists.
void	marshalEvent(FireableEventType eventType, Object event, DataOutput out) Marshal an event.
void	marshalHandle(ActivityHandle handle, DataOutput out) Marshal an activity handle.
void	releaseEventBuffer(FireableEventType eventType, Object event, ByteBuffer buffer) The SLEE invokes this method to notify the resource adaptor that a buffer it previously obtained from the resource adaptor via the getEventBuffer(javax.slee.resource.FireableEventType, java.lang.Object) method is no longer required.
Object	unmarshalEvent(FireableEventType eventType, DataInput in) Unmarshal a previously marshaled event.
ActivityHandle	unmarshalHandle(DataInput in) Unmarshal a previously marshaled activity handle.

Method Detail

getEstimatedEventSize

int getEstimatedEventSize(FireableEventType eventType,
                        Object event)

Get an estimate of the size (in bytes) of the marshaled form of the specified event or event type. This method is used by the SLEE to help size internal bufferes used for marshaling events. The resource adaptor should provide a best-guess estimate.

This method can be invoked in two ways:

• If the event argument is not null, the SLEE is requesting an estimate of the marshaled size of the specified event object. The eventType argument specifies the event type of the event object.
• If the event argument is null, the SLEE is requesting a general estimate of the marshaled size of all event objects of the event types specified by the eventType argument.

This method is a non-transactional method.

Parameters:

eventType - the event type the SLEE is requesting a marshaled size estimate for.

event - the event object that the SLEE is requesting a marshaled size estimate for. This may be null if the SLEE is requesting a general estimate for all event objects of the indicated event type.

Returns:

an estimate of the size, in bytes, of the marshaled form of the specified event or event type.

getEventBuffer

ByteBuffer getEventBuffer(FireableEventType eventType,
                        Object event)

Get a buffer containing an already marshaled for of the specified event, if such a buffer exists.

A resource adaptor may choose to cache buffers containing the network messages it has received which the resource adaptor subsequently generates event objects from. This method provides a resource adaptor with the opportunity to give the SLEE access to these buffers during event marshalling, allowing the SLEE to use the already marshaled form, rather than the SLEE and resource adaptor unnecessarily marshaling the event object again. The buffer returned by this should have a position and limit that encapsulates only the marshaled event data, ie. if a network buffer contains multiple messages then the resource adaptor should generate a new ByteBuffer object that provides a view of the requested event only.

A resource adaptor is not expected to marshal the event object during this method. If an existing marshaled form of the event object exists, the resource adaptor should return a reference to the buffer. If a marshaled form does not exist, the resource adaptor should return null from this method and the SLEE will default to using the marshalEvent(javax.slee.resource.FireableEventType, java.lang.Object, java.io.DataOutput) method to perform the actual event marshaling.

If a resource adaptor returns a reference to a buffer from this method, the resource adaptor must ensure that the contents of the buffer are not modified and remain valid until the SLEE notifies the resource adaptor that it no longer needs the buffer via the releaseEventBuffer(javax.slee.resource.FireableEventType, java.lang.Object, java.nio.ByteBuffer) method.

This method is a non-transactional method.

Parameters:

eventType - the event type of the event.

event - the event object the SLEE is requesting a buffer for.

Returns:

a buffer containing the marshaled form of the event, or null if no such buffer exists.

releaseEventBuffer

void releaseEventBuffer(FireableEventType eventType,
                      Object event,
                      ByteBuffer buffer)

The SLEE invokes this method to notify the resource adaptor that a buffer it previously obtained from the resource adaptor via the getEventBuffer(javax.slee.resource.FireableEventType, java.lang.Object) method is no longer required. The resource adaptor is therefore free to release any resources associated with the buffer as required.

This method is a non-transactional method.

Parameters:

eventType - the event type of the event.

event - the event object that the buffer was obtained for.

buffer - the buffer the resource adaptor provided to the SLEE for the event object.

marshalEvent

void marshalEvent(FireableEventType eventType,
                Object event,
                DataOutput out)
                  throws IOException

Marshal an event.

This method is a non-transactional method.

Parameters:

eventType - the event type of the event.

event - the event object to marshal.

out - a DataOutput object that the resource adaptor must use to write the marshaled event data to.

Throws:

IOException - if an I/O error occurs while marshaling the event.

unmarshalEvent

Object unmarshalEvent(FireableEventType eventType,
                    DataInput in)
                      throws IOException

Unmarshal a previously marshaled event.

This method is a non-transactional method.

Parameters:

eventType - the event type of the marshaled event.

in - a DataInput object that the resource adaptor uses to read the marshaled event data from.

Returns:

the unmarshaled event object.

Throws:

IOException - if an I/O error occurs while unmarshaling the event.

getEstimatedHandleSize

int getEstimatedHandleSize(ActivityHandle handle)

Get an estimate of the size (in bytes) of the marshaled form of an activity handle. This method is used by the SLEE to help size internal bufferes used for marshaling activity handles. The resource adaptor should provide a best-guess estimate.

This method can be invoked in two ways:

• If the handle argument is not null, the SLEE is requesting an estimate of the marshaled size of the specified activity handle.
• If the handle argument is null, the SLEE is requesting a general estimate of the marshaled size of all activity handles generated by the resource adaptor.

This method is a non-transactional method.

Parameters:

handle - the activity handle that the SLEE is requesting a marshaled size estimate for. This may be null if the SLEE is requesting a general estimate for all activity handles.

Returns:

an estimate of the size, in bytes, of the marshaled form of the activity handle, or all activity handles.

marshalHandle

void marshalHandle(ActivityHandle handle,
                 DataOutput out)
                   throws IOException

Marshal an activity handle.

This method is a non-transactional method.

Parameters:

handle - the activity handle to marshal.

out - a DataOutput object that the resource adaptor must use to write the marshaled activity handle to.

Throws:

IOException - if an I/O error occurs while marshaling the event.

unmarshalHandle

ActivityHandle unmarshalHandle(DataInput in)
                               throws IOException

Unmarshal a previously marshaled activity handle.

This method is a non-transactional method.

Parameters:

in - a DataInput object that the resource adaptor uses to read the marshaled activity handle data from.

Returns:

the unmarshaled activity handle object.

Throws:

IOException - if an I/O error occurs while unmarshaling the activity handle.