Package com.opencloud.rhino.facilities.sessionownership

Interface SessionOwnershipFacility

public interface SessionOwnershipFacility

The session ownership facility provides a mechanism for tracking which node is currently responsible for processing a given session.

Individual sessions are represented by SessionOwnershipRecord objects. These are records are stored in the session ownership facility according to its implementation. Records can be stored and retrieved using this API.

Since:

Rhino 2.6.1

Field Summary

Fields

Modifier and Type	Field	Description
static String	CONFIG_PROPERTY_NAME	Constant declaring the resource adaptor config property name where a SessionOwnershipFacility object can be obtained by a resource adaptor.

Method Summary

Modifier and Type	Method	Description
void	deleteRecord(String primaryKey, Set<String> additionalKeys)	Asynchronously attempt to delete all the session ownership records identified by the specified primary key and additional keys.
void	deleteRecord(String primaryKey, Set<String> additionalKeys, SessionOwnershipWriteListener listener)	Asynchronously attempt to delete all the session ownership records identified by the specified primary key and additional keys.
void	deleteRecordWithCasCompareSequence(int expectedStoredSequence, String primaryKey, Set<String> additionalKeys)	Asynchronously attempt to delete all the session ownership records identified by the specified primary key and additional keys.
void	deleteRecordWithCasCompareSequence(int expectedStoredSequence, String primaryKey, Set<String> additionalKeys, SessionOwnershipWriteListener listener)	Asynchronously attempt to delete all the session ownership records identified by the specified primary key and additional keys.
long	getDefaultTTL()	Get the default time-to-live for records stored in this session ownership facility.
SessionOwnershipRecord	peekRecord(String primaryKey)	Synchronously attempt to retrieve a locally cached copy of the session ownership record with the specified primary key.
Set<SessionOwnershipRecord>	peekRecordsByAdditionalKey(String additionalKey)	Synchronously attempt to retrieve locally cached copies of the session ownership records with the specified additional key.
void	retrieveRecord(String primaryKey, SessionOwnershipReadListener listener)	Asynchronously attempt to retrieve the session ownership record with the specified primary key.
void	retrieveRecordsByAdditionalKey(String additionalKey, SessionOwnershipReadListener listener)	Asynchronously attempt to retrieve all session ownership records with the specified additional key.
void	storeRecord(SessionOwnershipRecord sessionOwnershipRecord)	Asynchronously attempt to write a session ownership record into the session ownership store.
void	storeRecord(SessionOwnershipRecord sessionOwnershipRecord, long ttl)	Asynchronously attempt to write a session ownership record into the session ownership store.
void	storeRecord(SessionOwnershipRecord sessionOwnershipRecord, long ttl, SessionOwnershipWriteListener listener)	Asynchronously attempt to write a session ownership record into the session ownership store.
void	storeRecord(SessionOwnershipRecord sessionOwnershipRecord, SessionOwnershipWriteListener listener)	Asynchronously attempt to write a session ownership record into the session ownership store.
void	storeRecordWithCasCompareSequence(int expectedStoredSequence, SessionOwnershipRecord sessionOwnershipRecord)	Asynchronously attempt to write a session ownership record into the session ownership store.
void	storeRecordWithCasCompareSequence(int expectedStoredSequence, SessionOwnershipRecord sessionOwnershipRecord, long ttl)	Asynchronously attempt to write a session ownership record into the session ownership store.
void	storeRecordWithCasCompareSequence(int expectedStoredSequence, SessionOwnershipRecord sessionOwnershipRecord, long ttl, SessionOwnershipWriteListener listener)	Asynchronously attempt to write a session ownership record into the session ownership store.
void	storeRecordWithCasCompareSequence(int expectedStoredSequence, SessionOwnershipRecord sessionOwnershipRecord, SessionOwnershipWriteListener listener)	Asynchronously attempt to write a session ownership record into the session ownership store.
void	storeRecordWithCasCreateOnly(SessionOwnershipRecord sessionOwnershipRecord)	Asynchronously attempt to write a session ownership record into the session ownership store.
void	storeRecordWithCasCreateOnly(SessionOwnershipRecord sessionOwnershipRecord, long ttl)	Asynchronously attempt to write a session ownership record into the session ownership store.
void	storeRecordWithCasCreateOnly(SessionOwnershipRecord sessionOwnershipRecord, long ttl, SessionOwnershipWriteListener listener)	Asynchronously attempt to write a session ownership record into the session ownership store.
void	storeRecordWithCasCreateOnly(SessionOwnershipRecord sessionOwnershipRecord, SessionOwnershipWriteListener listener)	Asynchronously attempt to write a session ownership record into the session ownership store.
AdoptionResult	tryAdoptRecord(SessionOwnershipRecord recordToAdopt)	Synchronously inspect a session ownership record and potentially "adopt" (change ownership to this node) it using a CAS operation.
AdoptionResult	tryAdoptRecord(String recordPrimaryKey)	Synchronously reads the session ownership store to find the session ownership record and may then attempt to adopt by a CAS race.

Field Detail

CONFIG_PROPERTY_NAME

static final String CONFIG_PROPERTY_NAME

Constant declaring the resource adaptor config property name where a SessionOwnershipFacility object can be obtained by a resource adaptor.

The value of this constant is "slee-vendor:com.opencloud.rhino.facilities.sessionownership".

Since:

Rhino 2.6.1

See Also:

Constant Field Values

Method Detail

storeRecord

void storeRecord(SessionOwnershipRecord sessionOwnershipRecord)
          throws NullPointerException

Asynchronously attempt to write a session ownership record into the session ownership store. The write will blindly overwrite anything already stored against the specified record’s primary key and additional keys. If the write is successful, the TTL of the record will set with the default TTL of the session ownership store configured for the platform.

Parameters:

sessionOwnershipRecord - the record to store.

Throws:

NullPointerException - if sessionOwnershipRecord is null.

Since:

Rhino 2.6.1

storeRecord

void storeRecord(SessionOwnershipRecord sessionOwnershipRecord,
                 long ttl)
          throws NullPointerException

Asynchronously attempt to write a session ownership record into the session ownership store. The write will blindly overwrite anything already stored against the specified record’s primary key and additional keys. If the write is successful, the TTL of the record will set to the specified value.

Parameters:

sessionOwnershipRecord - the record to store.

ttl - the duration, in milliseconds, for which the session ownership store should keep the new record.

Throws:

NullPointerException - if sessionOwnershipRecord is null.

Since:

Rhino 2.6.1

storeRecord

void storeRecord(SessionOwnershipRecord sessionOwnershipRecord,
                 SessionOwnershipWriteListener listener)
          throws NullPointerException

Asynchronously attempt to write a session ownership record into the session ownership store. The write will blindly overwrite anything already stored against the specified record’s primary key and additional keys. If the write is successful, the TTL of the record will set with the default TTL of the session ownership store configured for the platform.

The result of the write will be reported to the specified listener (if any).

Parameters:

sessionOwnershipRecord - the record to store.

listener - a listener object that will receive a callback when the write result is available. May be null if no listener is needed.

Throws:

NullPointerException - if sessionOwnershipRecord is null.

Since:

Rhino 2.6.1

storeRecord

void storeRecord(SessionOwnershipRecord sessionOwnershipRecord,
                 long ttl,
                 SessionOwnershipWriteListener listener)
          throws NullPointerException

Asynchronously attempt to write a session ownership record into the session ownership store. The write will blindly overwrite anything already stored against the specified record’s primary key and additional keys. If the write is successful, the TTL of the record will set to the specified value.

The result of the write will be reported to the specified listener (if any).

Parameters:

sessionOwnershipRecord - the record to store.

ttl - the duration, in milliseconds, for which the session ownership store should keep the new record.

listener - a listener object that will receive a callback when the write result is available. May be null if no listener is needed.

Throws:

NullPointerException - if sessionOwnershipRecord is null.

Since:

Rhino 2.6.1

storeRecordWithCasCreateOnly

void storeRecordWithCasCreateOnly(SessionOwnershipRecord sessionOwnershipRecord)
                           throws NullPointerException

Asynchronously attempt to write a session ownership record into the session ownership store. The write will only be successful if there is no record already stored with the same primary key as that of the specified record. If the write is successful, the TTL of the record will set with the default TTL of the session ownership store configured for the platform.

Parameters:

sessionOwnershipRecord - the record to store.

Throws:

NullPointerException - if sessionOwnershipRecord is null.

Since:

Rhino 2.6.1

storeRecordWithCasCreateOnly

void storeRecordWithCasCreateOnly(SessionOwnershipRecord sessionOwnershipRecord,
                                  long ttl)
                           throws NullPointerException

Asynchronously attempt to write a session ownership record into the session ownership store. The write will only be successful if there is no record already stored with the same primary key as that of the specified record. If the write is successful, the TTL of the record will set to the specified value.

Parameters:

sessionOwnershipRecord - the record to store.

ttl - the duration, in milliseconds, for which the session ownership store should keep the new record.

Throws:

NullPointerException - if sessionOwnershipRecord is null.

Since:

Rhino 2.6.1

storeRecordWithCasCreateOnly

void storeRecordWithCasCreateOnly(SessionOwnershipRecord sessionOwnershipRecord,
                                  SessionOwnershipWriteListener listener)
                           throws NullPointerException

Asynchronously attempt to write a session ownership record into the session ownership store. The write will only be successful if there is no record already stored with the same primary key as that of the specified record. If the write is successful, the TTL of the record will set with the default TTL of the session ownership store configured for the platform.

The result of the write will be reported to the specified listener (if any).

Parameters:

sessionOwnershipRecord - the record to store.

listener - a listener object that will receive a callback when the write result is available. May be null if no listener is needed.

Throws:

NullPointerException - if sessionOwnershipRecord is null.

Since:

Rhino 2.6.1

storeRecordWithCasCreateOnly

void storeRecordWithCasCreateOnly(SessionOwnershipRecord sessionOwnershipRecord,
                                  long ttl,
                                  SessionOwnershipWriteListener listener)
                           throws NullPointerException

Asynchronously attempt to write a session ownership record into the session ownership store. The write will only be successful if there is no record already stored with the same primary key as that of the specified record. If the write is successful, the TTL of the record will set to the specified value.

The result of the write will be reported to the specified listener (if any).

Parameters:

sessionOwnershipRecord - the record to store.

ttl - the duration, in milliseconds, for which the session ownership store should keep the new record.

listener - a listener object that will receive a callback when the write result is available. May be null if no listener is needed.

Throws:

NullPointerException - if sessionOwnershipRecord is null.

Since:

Rhino 2.6.1

storeRecordWithCasCompareSequence

void storeRecordWithCasCompareSequence(int expectedStoredSequence,
                                       SessionOwnershipRecord sessionOwnershipRecord)
                                throws NullPointerException

Asynchronously attempt to write a session ownership record into the session ownership store. The write will only be successful if there already exists a session ownership record with the same primary key as the specified record and that record has a sequence number matching the specified expected sequence number. If the write is successful, the TTL of the record will set with the default TTL of the session ownership store configured for the platform.

Parameters:

expectedStoredSequence - the expected sequence number of the record currently stored that will be replaced.

sessionOwnershipRecord - the record to store.

Throws:

NullPointerException - if sessionOwnershipRecord is null.

Since:

Rhino 2.6.1

storeRecordWithCasCompareSequence

void storeRecordWithCasCompareSequence(int expectedStoredSequence,
                                       SessionOwnershipRecord sessionOwnershipRecord,
                                       long ttl)
                                throws NullPointerException

Asynchronously attempt to write a session ownership record into the session ownership store. The write will only be successful if there already exists a session ownership record with the same primary key as the specified record and that record has a sequence number matching the specified expected sequence number. If the write is successful, the TTL of the record will set to the specified value.

Parameters:

expectedStoredSequence - the expected sequence number of the record currently stored that will be replaced.

sessionOwnershipRecord - the record to store.

ttl - the duration, in milliseconds, for which the session ownership store should keep the new record.

Throws:

NullPointerException - if sessionOwnershipRecord is null.

Since:

Rhino 2.6.1

storeRecordWithCasCompareSequence

void storeRecordWithCasCompareSequence(int expectedStoredSequence,
                                       SessionOwnershipRecord sessionOwnershipRecord,
                                       SessionOwnershipWriteListener listener)
                                throws NullPointerException

Asynchronously attempt to write a session ownership record into the session ownership store. The write will only be successful if there already exists a session ownership record with the same primary key as the specified record and that record has a sequence number matching the specified expected sequence number. If the write is successful, the TTL of the record will set with the default TTL of the session ownership store configured for the platform.

The result of the write will be reported to the specified listener (if any).

Parameters:

expectedStoredSequence - the expected sequence number of the record currently stored that will be replaced.

sessionOwnershipRecord - the record to store.

listener - a listener object that will receive a callback when the write result is available. May be null if no listener is needed.

Throws:

NullPointerException - if sessionOwnershipRecord is null.

Since:

Rhino 2.6.1

storeRecordWithCasCompareSequence

void storeRecordWithCasCompareSequence(int expectedStoredSequence,
                                       SessionOwnershipRecord sessionOwnershipRecord,
                                       long ttl,
                                       SessionOwnershipWriteListener listener)
                                throws NullPointerException

Asynchronously attempt to write a session ownership record into the session ownership store. The write will only be successful if there already exists a session ownership record with the same primary key as the specified record and that record has a sequence number matching the specified expected sequence number. If the write is successful, the TTL of the record will set to the specified value.

The result of the write will be reported to the specified listener (if any).

Parameters:

expectedStoredSequence - the expected sequence number of the record currently stored that will be replaced.

sessionOwnershipRecord - the record to store.

ttl - the duration, in milliseconds, for which the session ownership store should keep the new record.

listener - a listener object that will receive a callback when the write result is available. May be null if no listener is needed.

Throws:

NullPointerException - if sessionOwnershipRecord is null.

Since:

Rhino 2.6.1

deleteRecord

void deleteRecord(String primaryKey,
                  Set<String> additionalKeys)
           throws NullPointerException

Asynchronously attempt to delete all the session ownership records identified by the specified primary key and additional keys. The caller must specify all additional keys, ie. the implementation will not do a lookup on primary key before deleting records. If an additional key is not provided, and a record with that key exists in the session ownership store, it will not be removed by this method.

Parameters:

primaryKey - the primary key of the session ownership record to be removed.

additionalKeys - the additional keys to remove.

Throws:

NullPointerException - if either argument is null.

Since:

Rhino 2.6.1

deleteRecord

void deleteRecord(String primaryKey,
                  Set<String> additionalKeys,
                  SessionOwnershipWriteListener listener)
           throws NullPointerException

Asynchronously attempt to delete all the session ownership records identified by the specified primary key and additional keys. The caller must specify all additional keys, ie. the implementation will not do a lookup on primary key before deleting records. If an additional key is not provided, and a record with that key exists in the session ownership store, it will not be removed by this method.

The result of the write will be reported to the specified listener (if any).

Parameters:

primaryKey - the primary key of the session ownership record to be removed.

additionalKeys - the additional keys to remove.

listener - a listener object that will receive a callback when the write result is available. May be null if no listener is needed.

Throws:

NullPointerException - if primaryKey or additionalKeys is null.

Since:

Rhino 2.6.1

deleteRecordWithCasCompareSequence

void deleteRecordWithCasCompareSequence(int expectedStoredSequence,
                                        String primaryKey,
                                        Set<String> additionalKeys)
                                 throws NullPointerException

Asynchronously attempt to delete all the session ownership records identified by the specified primary key and additional keys. The delete will only occur if there already exists a session ownership record with the same primary key as the specified record and that record has a sequence number matching the specified expected sequence number. The caller must specify all additional keys, ie. the implementation will not do a lookup on primary key before deleting records. If an additional key is not provided, and a record with that key exists in the session ownership store, it will not be removed by this method.

Parameters:

expectedStoredSequence - the expected sequence number of the record currently stored to be removed.

primaryKey - the primary key of the session ownership record to be removed.

additionalKeys - the additional keys to remove.

Throws:

NullPointerException - if primaryKey or additionalKeys is null.

Since:

Rhino 2.6.1

deleteRecordWithCasCompareSequence

void deleteRecordWithCasCompareSequence(int expectedStoredSequence,
                                        String primaryKey,
                                        Set<String> additionalKeys,
                                        SessionOwnershipWriteListener listener)
                                 throws NullPointerException

Asynchronously attempt to delete all the session ownership records identified by the specified primary key and additional keys. The delete will only occur if there already exists a session ownership record with the same primary key as the specified record and that record has a sequence number matching the specified expected sequence number. The caller must specify all additional keys, ie. the implementation will not do a lookup on primary key before deleting records. If an additional key is not provided, and a record with that key exists in the session ownership store, it will not be removed by this method.

The result of the write will be reported to the specified listener (if any).

Parameters:

expectedStoredSequence - the expected sequence number of the record currently stored to be removed.

primaryKey - the primary key of the session ownership record to be removed.

additionalKeys - the additional keys to remove.

listener - a listener object that will receive a callback when the write result is available. May be null if no listener is needed.

Throws:

NullPointerException - if primaryKey or additionalKeys is null.

Since:

Rhino 2.6.1

retrieveRecord

void retrieveRecord(String primaryKey,
                    SessionOwnershipReadListener listener)
             throws NullPointerException

Asynchronously attempt to retrieve the session ownership record with the specified primary key.

The result of the read will be reported to the specified listener (if any).

Parameters:

primaryKey - the primary key of the session ownership record to retrieve.

listener - a listener object that will receive a callback when the read result is available.

Throws:

NullPointerException - if either argument is null.

Since:

Rhino 2.6.1

retrieveRecordsByAdditionalKey

void retrieveRecordsByAdditionalKey(String additionalKey,
                                    SessionOwnershipReadListener listener)
                             throws NullPointerException

Asynchronously attempt to retrieve all session ownership records with the specified additional key.

Multiple records may have the same additional key, so more than one record may be returned by a single invocation of this method.

Parameters:

additionalKey - the additional key of the session ownership records to retrieve.

listener - a listener object that will receive a callback when the read result is available.

Throws:

NullPointerException - if either argument is null.

Since:

Rhino 2.6.1

peekRecord

SessionOwnershipRecord peekRecord(String primaryKey)
                           throws NullPointerException

Synchronously attempt to retrieve a locally cached copy of the session ownership record with the specified primary key.

Parameters:

primaryKey - the primary key of the session ownership record to retrieve.

Returns:

the session ownership record with the specified primary key if it is present in the local cache, or null if not.

Throws:

NullPointerException - if primaryKey is null.

Since:

Rhino 2.6.1

peekRecordsByAdditionalKey

Set<SessionOwnershipRecord> peekRecordsByAdditionalKey(String additionalKey)
                                                throws NullPointerException

Synchronously attempt to retrieve locally cached copies of the session ownership records with the specified additional key.

This method only returns copies of records that are present in the local cache. It is possible that a matching record exists in the session ownership store but not in the local cache, in which case it will not be included in the result returned from this method.

Parameters:

additionalKey - the additional key of the session ownership records to retrieve.

Returns:

a set of all of the locally cached session ownership records with the specified additional key.

Throws:

NullPointerException - if additionalKey is null.

Since:

Rhino 2.6.1

tryAdoptRecord

AdoptionResult tryAdoptRecord(SessionOwnershipRecord recordToAdopt)
                       throws NullPointerException,
                              IllegalArgumentException

Synchronously inspect a session ownership record and potentially "adopt" (change ownership to this node) it using a CAS operation.

A valid session ownership record for this operation must have:

• An owner URI in a format understood by Rhino

• a "com.metaswitch.rhino:cluster-view-id" attribute in the format understood by Rhino.

If the provided record is not valid, or Rhino does not understand any aspect of the record, an IllegalArgumentException will be thrown. A convergence name session ownership record satisfies the conditions above and may be successfully used by a resource adaptor with this method.

An adoption of the record is not attempted in the following cases:

• The ownerURI of the record is in another Rhino cluster.

  • In this case AdoptionResult.getType() will be AdoptionResultType.RECORD_NOT_SAME_CLUSTER. AdoptionResult.getClusterID() and AdoptionResult.getNodeID() will return the cluster ID and node ID of the current owner respectively.

• The owning node according to the ownerURI is an active member of the cluster.

  • In this case AdoptionResult.getType() will be AdoptionResultType.ALREADY_OWNED_BY_OTHER_NODE. AdoptionResult.getClusterID() will return the local cluster ID and AdoptionResult.getNodeID() will return the node ID of the current owner.

• The owning node according to the ownerURI is this node.

  • In this case AdoptionResult.getType() will be AdoptionResultType.ALREADY_OWNED_BY_THIS_NODE. AdoptionResult.getClusterID() and AdoptionResult.getNodeID() will return the cluster ID and node ID of this node respectively.

• The "com.metaswitch.rhino:cluster-view-id" attribute is set to a higher view ID than this node’s current view ID - such a case means that this node is waiting for a view ID change.

  • In Savanna clustering terms waiting for a view ID change means that an outstanding Configuration Change Message (CCM) is yet to be delivered to the node.

  • In this case AdoptionResult.getType() will be AdoptionResultType.RECORD_VIEW_ID_NEWER.

When the adoption CAS occurs, it uses the SessionOwnershipRecord.getSequenceNumber() for the compare and set, incrementing by one. The newly written record will contain the most recent cluster-view-id for this node, and the owner URI will be set such that this node will be recorded as the owner.

Parameters:

recordToAdopt - the record to adopt.

Returns:

an AdoptionResult indicating the outcome of the operation.

Throws:

NullPointerException - if recordToAdopt is null.

IllegalArgumentException - if recordToAdopt is not a valid session ownership record for this operation.

Since:

Rhino 2.6.2

tryAdoptRecord

AdoptionResult tryAdoptRecord(String recordPrimaryKey)
                       throws NullPointerException,
                              IllegalArgumentException

Synchronously reads the session ownership store to find the session ownership record and may then attempt to adopt by a CAS race.

This operation is logically equivalent to first retrieving the session ownership record (through retrieveRecord(String, SessionOwnershipReadListener), waiting for the callback to be delivered on the listener, then invoking tryAdoptRecord(SessionOwnershipRecord) passing the retrieved record as the argument.

If the session ownership store does not contain a record with the specified primary key, the AdoptionResult.getType() will be AdoptionResultType.RECORD_DOES_NOT_EXIST.

Otherwise this method has the same behaviour and contract as tryAdoptRecord(SessionOwnershipRecord).

Parameters:

recordPrimaryKey - the primary key of the record to adopt.

Returns:

an AdoptionResult indicating the outcome of the operation.

Throws:

NullPointerException - if recordPrimaryKey is null.

IllegalArgumentException - if the retrieved record is not valid or otherwise not understood by Rhino.

Since:

Rhino 2.6.2

getDefaultTTL

long getDefaultTTL()

Get the default time-to-live for records stored in this session ownership facility. Units are in milliseconds.

Returns:

the default time-to-live.

Since:

Rhino 2.6.1