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.
| Modifier and Type | Field and 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. |
| Modifier and Type | Method and 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.
|
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".
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.
sessionOwnershipRecord - the record to store.NullPointerException - if sessionOwnershipRecord is null.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.
sessionOwnershipRecord - the record to store.ttl - the duration, in milliseconds, for which the session ownership store should keep the new record.NullPointerException - if sessionOwnershipRecord is null.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).
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.NullPointerException - if sessionOwnershipRecord is null.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).
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.NullPointerException - if sessionOwnershipRecord is null.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.
sessionOwnershipRecord - the record to store.NullPointerException - if sessionOwnershipRecord is null.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.
sessionOwnershipRecord - the record to store.ttl - the duration, in milliseconds, for which the session ownership store should keep the new record.NullPointerException - if sessionOwnershipRecord is null.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).
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.NullPointerException - if sessionOwnershipRecord is null.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).
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.NullPointerException - if sessionOwnershipRecord is null.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.
expectedStoredSequence - the expected sequence number of the record currently stored that will be replaced.sessionOwnershipRecord - the record to store.NullPointerException - if sessionOwnershipRecord is null.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.
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.NullPointerException - if sessionOwnershipRecord is null.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).
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.NullPointerException - if sessionOwnershipRecord is null.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).
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.NullPointerException - if sessionOwnershipRecord is null.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.
primaryKey - the primary key of the session ownership record to be removed.additionalKeys - the additional keys to remove.NullPointerException - if either argument is null.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).
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.NullPointerException - if primaryKey or additionalKeys is null.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.
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.NullPointerException - if primaryKey or additionalKeys is null.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).
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.NullPointerException - if primaryKey or additionalKeys is null.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).
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.NullPointerException - if either argument is null.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.
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.NullPointerException - if either argument is null.SessionOwnershipRecord peekRecord(String primaryKey) throws NullPointerException
Synchronously attempt to retrieve a locally cached copy of the session ownership record with the specified primary key.
primaryKey - the primary key of the session ownership record to retrieve.null if not.NullPointerException - if primaryKey is null.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.
additionalKey - the additional key of the session ownership records to retrieve.NullPointerException - if additionalKey is null.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.
recordToAdopt - the record to adopt.AdoptionResult indicating the outcome of the operation.NullPointerException - if recordToAdopt is null.IllegalArgumentException - if recordToAdopt is not a valid session ownership record for this operation.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).
recordPrimaryKey - the primary key of the record to adopt.AdoptionResult indicating the outcome of the operation.NullPointerException - if recordPrimaryKey is null.IllegalArgumentException - if the retrieved record is not valid or otherwise not understood by Rhino.long getDefaultTTL()
Get the default time-to-live for records stored in this session ownership facility. Units are in milliseconds.