Reference


Contents

    xscmd utility reference
    HTTP command interface reference
    Release 2.0 Client API Specification
    com.ibm.websphere.objectgrid Package
    com.ibm.websphere.objectgrid.client Package com.ibm.websphere.objectgrid.spring Package com.ibm.websphere.objectgrid.plugins Package
    com.ibm.websphere.objectgrid.security Package
    com.ibm.websphere.objectgrid.config Package
    com.ibm.websphere.objectgrid.management Package
    AvailabilityState
    BackingMap
    ClientClusterContext
    ClientReplicableMap
    ClientReplicableMap.Mode
    ClientServerMultipleReplicationGroupMemberWriteTransactionCallbackException
    ConnectException
    CopyMode
    DuplicateKeyException
    IObjectGridException
    JavaMap
    KeyNotFoundException
    LockDeadlockException
    LockException
    LockInternalFailureException
    LockStrategy
    LockTimeoutException
    NoActiveTransactionException
    ObjectGrid
    ObjectGridException
    ObjectGridManager
    ObjectGridManagerFactory
    ObjectGridRuntimeException
    ObjectMap
    PartitionManager
    ReadOnlyException
    ReplicationVotedToRollbackTransactionException
    Session
    SessionNotReentrantException
    StateManager
    TTLType
    TargetNotAvailableException
    TransactionAffinityException
    TransactionAlreadyActiveException
    TransactionException
    TransactionQuiesceException
    TransactionTimeoutException
    TxID
    UnavailableServiceException
    UndefinedMapException
    Glossary


1. xscmd utility reference

The general format of xscmd utility commands follows. 

Usage: xscmd -c <cmdName> | -h <cmdName> | -lc [<cmdGroupName>] | -lcg
             [-cgc <className>] [-ca <support>] [-sp
             <profileName>] [-ks <filePath>] [-ts <filePath>] [-trf
             <filePath>] [-prot <protocol>] [-cxpv <provider>] [-trs
             <traceSpec>] [-al <alias>] [-pwd <password>] [-tsp <password>]
             [-cep <endpoints>] [-ksp <password>] [-arc <integer>] [-tt
             <type>] [-tst <type>] [-ssp <profileName>] [-kst <type>] [-cgp
             <property>] [-user <username>]

Options:
  -al,--alias <alias>                  Alias name in the keystore.

  -arc,--authRetryCount <integer>      The retry count for authentication if
                                       the credential is expired. If the value is set to 0, then
                                       authentication retries do not occur.

  -c,--command <cmdName>               Name of the command to execute

  -ca,--credAuth <support>             Set the client credential
                                       authentication support [Never,
                                       Supported, Required].

  -cep,--catalogEndPoints <endpoints>  Specifies one or more catalog service                                        endpoints in the format                                        <host>[:<listenerPort>][,<host>[:<liste
                                       nerPort>]]. Default endpoint:
                                       localhost:2809

  -cgc,--credGenClass <className>      Name of the class that
                                       implements the CredentialGenerator
                                       interface. This class is used to get
                                       credentials for clients.

  -cgp,--credGenProps <property>       Properties for the CredentialGenerator implementation                                        class. The properties are set to the object with the setProperties(String)
                                       method.

  -cxpv,--contextProvider <provider>   Context provider.  Examples: IBMJSSE2,
                                       IBMJSSE, IBMJSSEFIPS.

  -h,--help <cmdName>                  Invokes general command-line help

  -ks,--keyStore <filePath>            Absolute path to keystore. Example:
                                       /etc/test/security/server.public

  -ksp,--keyStorePassword <password>   Password to the keystore.

  -kst,--keyStoreType <type>           Keystore type. Example: JKS, JCEK,
                                       PKCS12.

  -lc,--listCommands <cmdGroupName>    List all commands for a command group

  -lcg,--listCommandGroups             List all command groups

  -prot,--protocol <protocol>          Protocol.  Examples: SSL, SSLv2,
                                       SSLv3, TLS, TLSv1.

  -pwd,--password <password>           eXtreme Scale password security
                                       credential

  -sp,--secProfile <profileName>       Profile name.

  -ssp,--saveSecProfile <profileName>  Save security parameter values in                                        security profile.

  -trf,--traceFile <filePath>          Absolute path to the generated trace file for xscmd command
                                       output 
  -trs,--traceSpec <traceSpec>         Trace specification for xscmd command output 
  -ts,--trustStore <filePath>          Absolute path to truststore. Example:
                                       /etc/test/security/server.public

  -tsp,--trustStorePassword <password> Truststore password 
  -tst,--trustStoreType <type>         Truststore type. Examples: JKS, JCEK,
                                       PKCS12.

  -tt,--transportType <type>           Transport layer security configuration                                        type.  Examples: TCP/IP,
                                       SSL-Supported, SSL-Required.

  -user,--username <username>          eXtreme Scale user name security
                                       credential

usage: xscmd -c <cmdName> | -h <cmdName> | -lc [<cmdGroupName>] | -lcg
             [-cgc <className>] [-ca <support>] [-sp <profileName>] [-ks
             <filePath>] [-ts <filePath>] [-trf <filePath>] [-prot <protocol>]
             [-cxpv <provider>] [-trs <traceSpec>] [-al <alias>] [-pwd
             <password>] [-tsp <password>] [-cep <endpoints>] [-ksp <password>]
             [-arc <integer>] [-tt <type>] [-tst <type>] [-ssp <profileName>]
             [-kst <type>] [-cgp <property>] [-user <username>]
Options:
 -al,--alias <alias>                    Alias name in the key store.
 -arc,--authRetryCount <integer>        The retry count for authentication if
                                        the credential is expired. If the value
                                        is set to 0, there will not be any
                                        authentication retry.
 -c,--command <cmdName>                 Name of the command to execute
 -ca,--credAuth <support>               Set the client credential authentication
                                        support [Never, Supported, Required].
 -cep,--catalogEndPoints <endpoints>    Specifies one or more catalog service                                         endpoints in the format                                         <host>[:<listenerPort>][,<host>[:<listen
                                        erPort>]]. Default endpoint:
                                        localhost:2809
 -cgc,--credGenClass <className>        Name of the class that
                                        implements the CredentialGenerator
                                        interface. This class is used to get
                                        credentials for clients.
 -cgp,--credGenProps <property>         Properties for the CredentialGenerator implementation                                         class. The properties are set to the object with the setProperties(String)
                                        method.
 -cxpv,--contextProvider <provider>     Context provider.  Examples: IBMJSSE2,
                                        IBMJSSE, IBMJSSEFIPS.
 -h,--help <cmdName>                    Invokes general command-line help
 -ks,--keyStore <filePath>              Absolute path to keystore. Example:
                                        /etc/test/security/server.public
 -ksp,--keyStorePassword <password>     Password to the keystore.
 -kst,--keyStoreType <type>             Keystore type. Example: JKS, JCEK,
                                        PKCS12.
 -lc,--listCommands <cmdGroupName>      List all commands for a command group
 -lcg,--listCommandGroups               List all command groups
 -prot,--protocol <protocol>            Protocol.  Examples: SSL, SSLv2, SSLv3,
                                        TLS, TLSv1.
 -pwd,--password <password>             eXtreme Scale password security
                                        credential
 -sp,--secProfile <profileName>         Profile name.
 -ssp,--saveSecProfile <profileName>    Save security parameter values in                                         security profile.
 -trf,--traceFile <filePath>            Absolute path to the generated trace file for xscmd command
                                        output  -trs,--traceSpec <traceSpec>           Trace specification for xscmd command output  -ts,--trustStore <filePath>            Absolute path to truststore. Example:
                                        /etc/test/security/server.public
 -tsp,--trustStorePassword <password>   Truststore password  -tst,--trustStoreType <type>           Truststore type. Examples: JKS, JCEK,
                                        PKCS12.
 -tt,--transportType <type>             Transport layer security configuration                                         type.  Examples: TCP/IP, SSL-Supported,
                                        SSL-Required.
 -user,--username <username>            eXtreme Scale user name security
                                        credential


All commands

The full list of xscmd utility commands follows. For further help and parameters for a specific command run xscmd -h command_name 

Command Name           Description
------------           -----------
balanceShardTypes      Attempt shard redistribution so that the ratio of primaries and replicas within each container server
                       are within one shard.

balanceStatus          Check the balance status of the data grid for the ObjectGrid and map set specified.

clearGrid              Clears data from the data grid.

dismissLink            Disconnects from the specified catalog service domain.

establishLink          Connects to the specified catalog service domain with                        the specified catalog service endpoints.

findByKey              Finds matching keys in a map.

getCatTraceSpec        Retrieves the trace specification for all the catalog                        servers that are known by this process.

getStatsSpec           Retrieves the statistics specification.

getTraceSpec           Retrieves the trace specification.

listAllJMXAddresses    Displays all JMX MBean server addresses.

listCoreGroups         List all core groups.

listHosts              Lists all hosts.

listObjectGridNames    Lists all known ObjectGrid instances and map sets.

listProfiles           Lists profiles.

osgiAll                Show all available OSGi service rankings. Use the -sn
                       option to display a single service.

osgiCheck              Check whether specified OSGi service rankings are                        available

osgiCurrent            Show all OSGi service rankings currently in use. Use                        the -sn option to display a single service.

osgiUpdate             Update the OSGi services to the specified rankings

overrideQuorum         Notify the catalog server to override quorum.

placementServiceStatus Displays the ObjectGrid placement operation status.

releaseShard           Releases the specified primary shard from the specified container server.

removeProfile          Remove profile from file system.

reserveShard           Reserves the specified primary shard on the specified
                       container server.

resumeBalancing        Attempts to balance and allow future balancing
                       attempts for the specified ObjectGrid instance and map
                       set.

revisions              Displays all known revision history.

routetable             Displays the current routing table.

setCatTraceSpec        Sets the trace specification for all the catalog                        servers known by this process.

setStatsSpec           Sets the statistics specification.

setTraceSpec           Trace specification in the form:
                       traceType1=traceLevel1=traceState1[:traceTypeN=traceLev
                       elN=traceStateN]*

showCoreGroupMembers   Shows all core group members.

showInfo               Retrieves the environment specifications including
                       installed versions and JVM information.

showLinkedPrimaries    Displays the primary shards and all of their foreign
                       or domestic linked primary shards

showMapSizes           Displays all map sizes.

showPlacement          Lists all container servers and their shards.

showProfile            Show the details of the specified profile.

showQuorumStatus       Displays catalog server quorum status.

suspendBalancing       Prevents future attempts to balance the specified
                       ObjectGrid instance and map set.

swapShardWithPrimary   Swaps the specified replica shard for the specified
                       container server with its primary shard.

teardown               Stops a list of catalog and container servers.

triggerPlacement       Triggers a placement operation for the specified
                       ObjectGrid instance and map set. The numInitialContainers value is ignored.

Command Name           Description
------------           -----------
balanceShardTypes      Attempt shard redistribution so that the ratio of primaries/replicas within each container are to within
                       one shard.

balanceStatus          Check the balance status of the grid for the ObjectGrid                        and MapSet specified

clearGrid              Clears data from the data grid.

dismissLink            Disconnects from the specified catalog service domain.

establishLink          Connects to the specified catalog service domain with                        the specified catalog service endpoints.

getCatTraceSpec        Retrieves the trace specification for all the catalog                        servers that are known by this process.

getStatsSpec           Retrieves the statistics specification.

getTraceSpec           Retrieves the trace specification.

listAllJMXAddresses    Displays all JMX MBean server addresses.

listCoreGroups         List all core groups.

listHosts              Lists all hosts.

listObjectGridNames    Lists all known ObjectGrid instances and map sets.

listProfiles           Lists profiles.

osgiAll                Show all available OSGi service rankings. Use the -sn
                       option to display a single service.

osgiCheck              Check whether specified OSGi service rankings are                        available

osgiCurrent            Show all OSGi service rankings currently in use. Use the -sn option to display a single service.

osgiUpdate             Update the OSGi services to the specified rankings

overrideQuorum         Notify the catalog server to override quorum.

placementServiceStatus Displays the ObjectGrid placement operation status.

releaseShard           Releases the specified primary shard from the specified
                       container server.

removeProfile          Remove profile from file system.

reserveShard           Reserves the specified primary shard on the specified
                       container server.

resumeBalancing        Attempts to balance and allow future balancing attempts
                       for the specified ObjectGrid instance and map set.

revisions              Displays all known revision history.

routetable             Displays the current routing table.

setCatTraceSpec        Sets the trace specification for all the catalog servers
                       known by this process.

setStatsSpec           Sets the statistics specification.

setTraceSpec           Trace specification in the form:
                       traceType1=traceLevel1=traceState1[:traceTypeN=traceLevelN=traceStateN]*

showCoreGroupMembers   Shows all core group members.

showLinkedPrimaries    Displays the primary shards and all of their foreign or                        domestic linked primary shards

showMapSizes           Displays all map sizes.

showPlacement          Lists all container servers and their shards.

showProfile            show the details of the specified profile.

showQuorumStatus       Displays catalog server quorum status.

suspendBalancing       Prevents future attempts to balance the specified
                       ObjectGrid instance and map set.

swapShardWithPrimary   Swaps the specified replica shard for the specified
                       container server with its primary shard.

teardown               Stops a list of catalog and container servers.

triggerPlacement       Triggers a placement operation for the specified
                       ObjectGrid instance and map set. The numInitialContainers value is ignored.


2. HTTP command interface reference

With the HTTP command interface, we can run operations on your appliance, configure appliance settings, and administer data grids, collectives, and zones.

List of APPLIANCE commands

 

 
CreateAdminTrace

Description: 
Adds or modifies an existing administrative trace string.

Required Parameters: 


traceName   Name of the trace.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "traceName": "AutoCustomLogger", "stopOnTaskFailure": "true", "command": "CreateAdminTrace" } }

Command Type: 
appliance

 

 
CreateDataCacheTrace

Description: 
Adds or modifies an existing data cache trace string.

Required Parameters: 


traceName   Name of the trace.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "traceName": "autoDataCacheLogger", "stopOnTaskFailure": "true", "command": "CreateDataCacheTrace" } }

Command Type: 
appliance

 

 
CreateSNMPCommunity

Description: 
Creates a Simple Network Management Protocol (SNMP) community.

Required Parameters: 


hostRestriction   (Optional) Specifies an IP address on which to restrict SNMP communication. Communication with any other IP address or subnet is denied.
communityName   Name of the SNMP community to create.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "hostRestriction": "autorestriction", "communityName": "autocommunity", "command": "CreateSNMPCommunity" } }

Command Type: 
appliance

 

 
DeleteSNMPCommunity

Description: 
Deletes a Simple Network Management Protocol (SNMP) community.

Required Parameters: 


communityName   Name of SNMP community to delete.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "communityName": "autocommunity", "command": "DeleteSNMPCommunity" } }

Command Type: 
appliance

 

 
EnableCreateAccount

Description: 
Enables a setting that allows users to initiate the creation of their own accounts.

Required Parameters: 


enable   Enables account creation. Set the value to false to disable account creation. Set the value to true to enable account creation.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "enable": "true", "stopOnTaskFailure": "true", "command": "EnableCreateAccount" } }

Command Type: 
appliance

 

 
 
EnablePasswordReset

Description: 
Enables the ability to reset the xcadmin password with a serial connection. No other credentials or SMTP messages are required.

Required Parameters: 


enable   Enables the password to be reset. Set true to enable password resets.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "enable": "true", "stopOnTaskFailure": "true", "command": "EnablePasswordReset" } }

Command Type: 
appliance

 

 
EnableSNMP

Description: 
Enables or disables Simple Network Management Protocol (SNMP).

Required Parameters: 


enable   Enables SNMP. Set the value to false to disable SNMP. Set true to enable SNMP.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "enable": "true", "stopOnTaskFailure": "true", "command": "EnableSNMP" } }

Command Type: 
appliance

 

 
ModifyAdministratorEmail

Description: 
Changes the default administrator email address.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
administratorEmail   Specifies a new email address for the default administrator account.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "command": "ModifyAdministratorEmail", "administratorEmail": "somenewname@us.ibm.com" } }

Command Type: 
appliance

 

 
ModifyAdministratorName

Description: 
Changes the default administrator account name.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
administratorName   New name for the default administrator account.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "administratorName": "somenewname", "command": "ModifyAdministratorName" } }

Command Type: 
appliance

 

 
ModifyAdministratorPassword

Description: 
Changes the password for the default administrator account.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
passwordVerification   Specifies a new default administrator account password, entered a second time for verification.
newPassword   Specifies a new default administrator account password.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "passwordVerification": "somepass", "newPassword": "somepass", "command": "ModifyAdministratorPassword" } }

Command Type: 
appliance

 

 
ModifyAdminDefaultTrace

Description:
Changes the trace level for the administrative default logger.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
traceLevel   Trace level. Valid values: OFF, SEVERE, WARNING, or INFO.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "command": "ModifyAdminDefaultTrace", "traceLevel": "SEVERE" } }

Command Type: 
appliance

 

 
ModifyAdminTrace

Description: 
Changes an administrative logger trace level.

Required Parameters: 


traceName   Name of the trace to modify.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
traceLevel   Trace level. Valid values: OFF, SEVERE, WARNING, INFO, FINE, FINER, FINEST, ALL.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "traceName": "autoCustomLogger", "stopOnTaskFailure": "true", "command": "ModifyAdminTrace", "traceLevel": "SEVERE" } }

Command Type: 
appliance

 

 
ModifyDataCacheTrace

Description: 
Adds or modifies an existing data cache trace string.

Required Parameters: 


traceName   Name of the trace.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
traceLevel   Trace level. Valid values: OFF, SEVERE, WARNING, INFO, FINE, FINER, FINEST, ALL.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "traceName": "autoDataCacheLogger", "stopOnTaskFailure": "true", "command": "ModifyDataCacheTrace", "traceLevel": "SEVERE" } }

Command Type: 
appliance

 

 
ModifyNtpServers

Description: 
Changes the list of Network Time Protocol (NTP) servers.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
listOfServers   Specifies a list of comma-separated Network Time Protocol (NTP) servers.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "listOfServers": "time.nist.gov,10.10.2.2", "command": "ModifyNtpServers" } }

Command Type: 
appliance

 

 
ModifySearchFilterUsers

Description: 
Changes the Lightweight Directory Access Protocol (LDAP) search filter for users.

Required Parameters: 


ldapUserIdSearchFilterPattern   LDAP user search filter pattern.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "ldapUserIdSearchFilterPattern": "(&(uid={0})(objectclass=inetOrgPerson))", "stopOnTaskFailure": "true", "command": "ModifySearchFilterUsers" } }

Command Type: 
appliance

 

 
ModifySMTPServer

Description: 
Changes the Simple Mail Transfer Protocol (SMTP) server.

Required Parameters: 


hostName   SMTP host address.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "hostName": "sicdsjc", "stopOnTaskFailure": "true", "command": "ModifySMTPServer" } }

Command Type: 
appliance

 

 
ModifySMTPEmail

Description: 
Changes the reply-to email address used for sending passwords that are reset by users.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
emailAddress   Specifies the reply-to email address. Use the email address for the administrator.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "emailAddress": "admin@mycompany.com", "command": "ModifySMTPEmail" } }

Command Type: 
appliance

 

 
ModifyTimeZone

Description: 
Changes the time zone for the appliance.

Required Parameters: 


localTimeZone   New time zone as an abbreviated string. Valid values: EST : Eastern Standard Time
CST : Central Standard Time
MST : Mountain Standard Time
PST : Pacific Standard Time
HAST : Hawaii
AKST : Alaska
AST : Atlantic
UTC : Coordinated Universal Time
GMT : Greenwich Mean Time
CET : Central Europe
EET : Eastern Europe
MSK : Moscow
AST_ARABIA : Arabia
KRT : Pakistan
IST : India
NOVT : Novosibirsk
CST_CHINA : China
JST : Japan
AWST : Australia West
ACST : Australia Central
AEST : Australia East
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "localTimeZone": "EST", "command": "ModifyTimeZone" } }

Command Type: 
appliance

 

 
PingRemoteHost

Description: 
Tests the visibility of a host from this appliance.

Required Parameters: 


hostName   IP address or host name of the remote host.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "hostName": "io03.rtp.raleigh.ibm.com", "stopOnTaskFailure": "true", "command": "PingRemoteHost" } }

Command Type: 
appliance

 

 
RemoveAdminTrace

Description: 
Removes an existing administrative console trace string.

Required Parameters: 


traceName   Name of the trace.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "traceName": "AutoCustomLogger", "stopOnTaskFailure": "true", "command": "RemoveAdminTrace" } }

Command Type: 
appliance

 

 
RemoveDataCacheTrace

Description: 
Removes an existing data cache trace string.

Required Parameters: 


traceName   Name of the trace.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "traceName": "autoDataCacheLogger", "stopOnTaskFailure": "true", "command": "RemoveDataCacheTrace" } }

Command Type: 
appliance

 

 
RestartAppliance

Description: 
Restarts or shuts down the appliance.

Required Parameters: 


immediate   Specifies if the appliance waits to complete active tasks before restarting. If the value is set to true, the appliance restarts immediately. If the value is set to false, the appliance waits for all active tasks to complete before restarting.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
shutdown   Specifies if the appliance restarts or shuts down. If the value is set to true, the appliance is shut down. If the value is set to false, the appliance restarts.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "immediate": "false", "stopOnTaskFailure": "true", "shutdown": "true", "command": "RestartAppliance" } }

Command Type: 
appliance

 

 
List of COLLECTIVE commands
 
AddRoleToGroup

Description: 
Assigns an access role to a group. The defined roles are: appliance administration, appliance monitoring, or data cache creation.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
role   Specifies the role to assign to the group. Valid values: 2 = appliance administration, 3 = appliance monitoring, 5 = data cache creation.
groupName   Name of the group that is being assigned to a role.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "role": "5", "groupName": "autoGroup1003", "command": "AddRoleToGroup" } }

 

 

Command Type: 
collective
AddRoleToUser

Description: 
Assigns an access role to a user. The defined roles are: appliance administration, appliance monitoring, or data cache creation.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
role   Specifies the role to assign to the user. Valid values: 2 = appliance administration, 3 = appliance monitoring, 5 = data cache creation.
userName   Name of the user that is being assigned a role.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "role": "2", "userName": "autoUser1003", "command": "AddRoleToUser" } }

Command Type: 
collective

 

 
AddApplianceToCollective

Description: 
Adds an existing appliance to the current collective.

Required Parameters: 


applianceIP   IP address of the appliance to add to the collective.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
zoneName   Name of the zone to which we want to assign the appliance.
waitOnTask   Specifies whether to wait on the completion of the task associated with the command. If the value is set to true, wait on the completion of the task. If the value is set to false, do not wait on the completion of the task.
secretKey   Specifies the secret key of the appliance.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "applianceIP": "192.168.222.128", "zoneName": "DefaultZone", "waitOnTask": "true", "command": "AddApplianceToCollective", "secretKey": "P5Xa4F8MQeSxuuhKxnaStw==" } }

Command Type: 
collective

 

 
CreateGroup

Description: 
Creates a new group. Groups are useful for assigning multiple users the same set of roles.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
groupName   Specifies a name for the new group. Group names must be unique.
groupDescription   Specifies a description of the group and its users.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "groupName": "autoGroup1003", "command": "CreateGroup", "groupDescription": "this group is huge" } }

Command Type: 
collective

 

 
CreateUser

Description: 
Creates a new user.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
fullUserName   Specifies a full name for the user. Example: John E. Doe.
passwordVerification   Password, entered a second time for verification.
userPassword   Specifies a new password for the selected user.
userName   Specifies a short name for the new user. Example: xcadmin.
emailAddress   Specifies an email address for the new user.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "fullUserName": "someuser isme", "passwordVerification": "someuserpass", "userPassword": "someuserpass", "userName": "someuser", "emailAddress": "someuser@us.ibm.com", "command": "CreateUser" } }

Command Type: 
collective

 

 
DeleteGroup

Description: 
Deletes a group. Users that belonged to the group no longer belong to the group and might lose any assigned roles.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
groupName   Name of a defined group.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "groupName": "autoGroup1003", "command": "DeleteGroup" } }

Command Type: 
collective

 

 
DeleteUser

Description: 
Deletes a user. If the user belongs to a group, the user is removed from the group.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
userName   Name of a defined user.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "userName": "autoUser1003", "command": "DeleteUser" } }

Command Type: 
collective

 

 
ModifyGroupDescription

Description: 
Changes the description of a selected group.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
groupName   Name of a defined group.
groupDescription   Specifies a description of the group and its users.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "groupName": "somegroup", "command": "ModifyGroupDescription", "groupDescription": "somegroupdesc" } }

Command Type: 
collective

 

 
ModifyUserEmail

Description: 
Changes the email address for a user.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
userName   Specifies the user name of the user to update.
emailAddress   Specifies a new email address for the user.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "userName": "user1", "emailAddress": "user1@mycompany.com", "command": "ModifyUserEmail" } }

Command Type: 
collective

 

 
AddUserToGroup

Description: 
Adds a user to a group. After the user is added to the group, the user has the roles that are assigned to the selected group only. Any individual user roles are lost.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
userName   Name of a defined user.
groupName   Name of a defined group.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "userName": "autoUser1003", "groupName": "autoGroup1003", "command": "AddUserToGroup" } }

Command Type: 
collective

 

 
ModifyUserPassword

Description: 
Changes the password for a specified user.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
passwordVerification   New password for the selected user, entered a second time for verification.
userName   Name of the user to update.
newPassword   Specifies a new password for the selected user.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "passwordVerification": "newpass", "userName": "autoUser1003", "newPassword": "newpass", "command": "ModifyUserPassword" } }

Command Type: 
collective

 

 
RemoveApplianceFromCollective

Description: 
Removes an existing appliance from the current collective.

Required Parameters: 


applianceIP   IP address of the appliance to be removed.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
waitOnTask   Specifies whether to wait on the completion of the task associated with the command. If the value is set to true, wait on the completion of the task. If the value is set to false, do not wait on the completion of the task.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "applianceIP": "192.168.222.128", "waitOnTask": "true", "command": "RemoveApplianceFromCollective" } }

Command Type: 
collective

 

 
RemoveRoleFromUser

Description: 
Removes an access role from a user. The defined roles are: appliance administration, appliance monitoring, or data cache creation.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
role   Specifies the role to remove from the user. Valid values: 2 = appliance administration, 3 = appliance monitoring, 5 = data cache creation.
userName   Name of for which we are removing an access role.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "role": "2", "userName": "autoUser1003", "command": "RemoveRoleFromUser" } }

Command Type: 
collective

 

 
RemoveUserFromGroup

Description: 
Removes a user from a group. After a user is removed from a group, the user continues to have the same roles as the group. However, the user roles for the user no longer change when the group roles change. You must modify the user roles for the selected user individually.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
userName   Name of a defined user.
groupName   Name of a defined group.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "userName": "autoUser1003", "groupName": "autoGroup1003", "command": "RemoveUserFromGroup" } }

Command Type: 
collective

 

 
RemoveRoleFromGroup

Description: 
Removes an access role from a group. The defined roles are: appliance administration, appliance monitoring, or data cache creation.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
role   Specifies the role to remove from the group. Valid values: 2 = appliance administration, 3 = appliance monitoring, 5 = data cache creation.
groupName   Name of the group for which we are removing an access role.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "role": "5", "groupName": "autoGroup1003", "command": "RemoveRoleFromGroup" } }

Command Type: 
collective

 

 
ViewAllGroups

Description: 
Displays information about all groups.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "command": "ViewAllGroups" } }

Command Type: 
collective

 

 
ViewAllUsers

Description: 
Displays the information for every user.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "command": "ViewAllUsers" } }

Command Type: 
collective

 

 
ViewGroup

Description: 
Displays information about a selected group.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
groupName   Name of a defined group.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "groupName": "autoGroup1003", "command": "ViewGroup" } }

Command Type: 
collective

 

 
ViewMemberDetails

Description: 
Displays information about a member in a collective.

Required Parameters: 


applianceIP   IP Address of the member.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "applianceIP": "192.168.222.128", "command": "ViewMemberDetails" } }

Command Type: 
collective

 

 
ViewUser

Description: 
Displays information about a selected user.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
userName   Name of a defined user.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "userName": "autoUser1003", "command": "ViewUser" } }

Command Type: 
collective
List of GRID commands

 

 
ClearGrid

Description: 
Clears data from a data grid.

Required Parameters: 


gridName   Name of the data grid to be cleared.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridName": "myGrid", "stopOnTaskFailure": "true", "command": "ClearGrid" } }

Command Type: 
grid

 

 
CreateGrid

Description: 
Creates a new simple, dynamic cache, or session data grid.

Required Parameters: 


gridType   Type of data grid to create. Valid values: simple, dynamic, or session.
gridName   Name of the data grid to create.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
waitOnTask   Specifies whether to wait on the completion of the task associated with the command. If the value is set to true, wait on the completion of the task. If the value is set to false, do not wait on the completion of the task.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridType": "simple", "gridName": "myGrid", "stopOnTaskFailure": "true", "waitOnTask": "true", "command": "CreateGrid" } }

Command Type: 
grid

 

 
DeleteGrid

Description: 
Deletes a data grid.

Required Parameters: 


gridName   Name of the data grid to delete.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
waitOnTask   Specifies whether to wait on the completion of the task associated with the command. If the value is set to true, wait on the completion of the task. If the value is set to false, do not wait on the completion of the task.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridName": "myGrid", "stopOnTaskFailure": "true", "command": "DeleteGrid" } }

Command Type: 
grid

 

 
ExportGrid

Description: 
(Simple data grids only) Exports data grid information to XML.

Required Parameters: 


gridName   Name of the data grid to export.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridName": "myGrid", "stopOnTaskFailure": "true", "command": "ExportGrid" } }

Command Type: 
grid

 

 
GrantGroupAccess

Description: 
Gives a group access rights to a data grid.

Required Parameters: 


gridName   Name of the data grid to grant access rights.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
groupName   Name of the group to grant the given access rights.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridName": "myGrid", "stopOnTaskFailure": "true", "groupName": "somegroup", "command": "GrantGroupAccess" } }

Command Type: 
grid

 

 
GrantUserAccess

Description: 
Gives a user access rights to a data grid.

Required Parameters: 


gridName   Name of the data grid to which the user is assigned access.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
userName   Name of the user to give access rights.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridName": "myGrid", "stopOnTaskFailure": "true", "userName": "someuser", "command": "GrantUserAccess" } }

Command Type: 
grid

 

 
ModifyGridCapacity

Description: 
Changes the capacity for a simple data grid.

Required Parameters: 


gridName   Name of the data grid to update.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
useLRU   (Simple data grids only) Enables least recently used (LRU) eviction when set to true.
waitOnTask   Specifies whether to wait on the completion of the task associated with the command. If the value is set to true, wait on the completion of the task. If the value is set to false, do not wait on the completion of the task.
gridCapLimit   Maximum capacity for the selected data grid in megabytes.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridName": "myGrid", "stopOnTaskFailure": "true", "useLRU": "false", "waitOnTask": "true", "command": "ModifyGridCapacity", "gridCapLimit": "10" } }

Command Type: 
grid

 

 
ModifyGridSecurity

Description: 
Changes the security settings for a data grid.

Required Parameters: 


securityEnabled   Enables security for the data grid when set to true.
gridName   Name of the data grid to update.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
authorizationEnabled   Enables authorization for the data grid when set to true.
waitOnTask   Specifies whether to wait on the completion of the task associated with the command. If the value is set to true, wait on the completion of the task. If the value is set to false, do not wait on the completion of the task.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "securityEnabled": "false", "gridName": "myGrid", "stopOnTaskFailure": "true", "authorizationEnabled": "false", "waitOnTask": "true", "command": "ModifyGridSecurity" } }

Command Type: 
grid

 

 
ModifyGridReplication

Description: 
Changes the replication settings for a data grid.

Required Parameters: 


gridName   Name of the data grid to update.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
maximumSyncReplicas   Maximum number of synchronous replicas for this data grid.
maximumAsyncReplicas   Maximum number of asynchronous replicas for this data grid.
waitOnTask   Specifies whether to wait on the completion of the task associated with the command. If the value is set to true, wait on the completion of the task. If the value is set to false, do not wait on the completion of the task.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridName": "myGrid", "stopOnTaskFailure": "true", "maximumSyncReplicas": "4", "maximumAsyncReplicas": "2", "waitOnTask": "true", "command": "ModifyGridReplication" } }

Command Type: 
grid

 

 
ModifyGridTTL

Description: 
(Simple data grids only) Changes time to live (TTL) settings for the data grid.

Required Parameters: 


gridName   Name of the data grid to update.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
gridTTL   Amount of time, in seconds, to keep data before evicting the data from data grid.
waitOnTask   Specifies whether to wait on the completion of the task associated with the command. If the value is set to true, wait on the completion of the task. If the value is set to false, do not wait on the completion of the task.
defaultMapEvictorType   (Optional) Time to live eviction type used for the default map. Valid values: NONE, CREATION_TIME, LAST_ACCESS_TIME, LAST_UPDATE_TIME.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridName": "myGrid", "stopOnTaskFailure": "true", "gridTTL": "60000", "waitOnTask": "true", "defaultMapEvictorType": "CREATION_TIME", "command": "ModifyGridTTL" } }

Command Type: 
grid

 

 
 

 

 
ModifyGroupAccess

Description: 
Changes the group access rights for a data grid.

Required Parameters: 


gridName   Name of the data grid to update.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
groupName   Name of the group for which we want to modify access rights.
accessType   Type of access to give to the group. Valid values: 1 = read, 2 = write, 3 = create, 4 = all.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridName": "myGrid", "stopOnTaskFailure": "true", "groupName": "somegroup", "command": "ModifyGroupAccess", "accessType": "1" } }

Command Type: 
grid

 

 
ModifyUserAccess

Description: 
Changes user access rights for a data grid.

Required Parameters: 


gridName   Name of the data grid to update.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
userName   Name of the user for which access rights are being updated.
accessType   Type of access to give to the user. Valid values: 1 = read, 2 = write, 3 = create, 4 = all.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridName": "myGrid", "stopOnTaskFailure": "true", "userName": "someuser", "command": "ModifyUserAccess", "accessType": "1" } }

Command Type: 
grid

 

 
RemoveGroupAccess

Description: 
Removes the access rights for a group to a data grid.

Required Parameters: 


gridName   Name of the data grid to update.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
groupName   Name of the group for which to remove access rights.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridName": "myGrid", "stopOnTaskFailure": "true", "groupName": "Everyone", "command": "RemoveGroupAccess" } }

Command Type: 
grid

 

 
RemoveUserAccess

Description: 
Removes access rights to a data grid for a specified user.

Required Parameters: 


gridName   Name of the data grid to update.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.
userName   Name of the user for which we are removing access rights.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridName": "myGrid", "stopOnTaskFailure": "true", "userName": "someuser", "command": "RemoveUserAccess" } }

Command Type: 
grid

 

 
ViewAllGrids

Description: 
Displays information for all simple, dynamic cache, or session grids.

Required Parameters: 


gridType   Type of data grid to display. The types include: simple, dynamic, or session.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridType": "simple", "stopOnTaskFailure": "true", "command": "ViewAllGrids" } }

Command Type: 
grid

 

 
ViewGrid

Description: 
Displays information for a data grid.

Required Parameters: 


gridName   Name of the data grid to be viewed.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridName": "myGrid", "stopOnTaskFailure": "true", "command": "ViewGrid" } }

Command Type: 
grid

 

 
ViewGridAccessList

Description: 
Displays the list of users and groups that can access the specified data grid.

Required Parameters: 


gridName   Name of the data grid to which access list is retrieved.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "gridName": "myGrid", "stopOnTaskFailure": "true", "command": "ViewGridAccessList" } }

Command Type: 
grid

 

 
List of TASK commands
 
DeleteTask

Description: 
Deletes a task.

Required Parameters: 


taskId   ID of task to delete.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "taskId": "appliance_10003", "stopOnTaskFailure": "true", "command": "DeleteTask" } }

Command Type: 
task

 

 
ViewAllTasks

Description: 
Displays all tasks.

Required Parameters: 


stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "stopOnTaskFailure": "true", "command": "ViewAllTasks" } }

Command Type: 
task

 

 
ViewTask

Description: 
Displays a task.

Required Parameters: 


taskId   Specifies the Task ID.
stopOnTaskFailure   Specifies whether to stop running the batch routine when the task fails. If the value is set to true, the batch routine stops. If the value is false or blank, the batch routine does not stop. Applies to commands that are run in batch processes only.


Result Parameters: 


status   Specifies the status of the command that was run. The result can be either success or failed.
commandName   Name of the HTTP command interface command that was run.
commandResult   A JSON-formatted statement that contains the result of the command that was run.
errorMessage   A message that explains the reason for the failure, if the command failed.


Example: 
{ "task": { "taskId": "appliance_10003", "stopOnTaskFailure": "true", "command": "ViewTask" } }

Command Type: 
task

 

 


Packages com.ibm.websphere.objectgrid
These are the main application APIs for the ObjectGrid. com.ibm.websphere.objectgrid.client
This package contains the primary interfaces and classes for setting behaviors for ObjectGrid clients for this process. com.ibm.websphere.objectgrid.config
This package contains the interfaces and a factory class for creating ObjectGrid configuration objects programatically. com.ibm.websphere.objectgrid.management
This package contains the interfaces for all ObjectGrid MBeans. com.ibm.websphere.objectgrid.plugins
These are the interfaces for adding plugins to the Grid core framework. com.ibm.websphere.objectgrid.plugins.builtins
This package contains built-in plugins for ObjectGrid core. com.ibm.websphere.objectgrid.security
This package has the class MapPermission and class AdminPermission which represents the permissions for to access the ObjectGrid maps and ObjectGrid administration respectively. com.ibm.websphere.objectgrid.security.config
This package contains the ObjectGrid client security configurations. om.ibm.websphere.objectgrid.security.plugins
This package contains the interfaces for adding plug-ins to the ObjectGrid security framework and assoicated Exception classes. com.ibm.websphere.objectgrid.security.plugins.builtins
This package contains the built-in implementation for the security plugins. com.ibm.websphere.objectgrid.spring
This package holds the Spring specific APIs for ObjectGrid.

 


Package com.ibm.websphere.objectgrid

These are the main application APIs for the ObjectGrid.

See:
          Description

Interface Summary
BackingMap
This is the public interface to the BackingMap.
ClientClusterContext
This interface is a context to represent which cluster/domain the client connected to using one of the ObjectGridManager.connect methods.
ClientReplicableMap
This interface represents a replicable client map.
IObjectGridException
This interface is used to ensure JDK 1.4 Throwable chaining behavior for all exceptions thrown by ObjectGrid even when an earlier JDK is used (e.g.
JavaMap
This interface is a handle to a named Map.
ObjectGrid
This object is used for creating sessions to the ObjectGrid.
ObjectGridManager
ObjectGridManager is responsible for creating or retrieving local ObjectGrid instances and connecting to distributed ObjectGrid servers.
ObjectMap
This is a handle to a named Map.
PartitionManager
This interface will be used for calculating the proper partition for a given input key.
Session
This interface represents a session container for ObjectMaps.
StateManager
The StateManager can be used to retrieve the availability state of an ObjectGrid.
TxID
This interface is an opaque identifier for a transaction.
 

Class Summary
AvailabilityState
Each shard in a distributed ObjectGrid has an availability state associated with it.
ClientReplicableMap.Mode
Client Replication mode
CopyMode
This class is used to define the "copy" mode when the setCopyMode method of the BackingMap interface is used.
LockStrategy
LockStrategy provides an enumerated type idiom for use on the BackingMap.setLockStrategy(LockStrategy) method.
ObjectGridManagerFactory
This factory class is a high level helper class to get ObjectGridManager instances.
TTLType
Every BackingMap in ObjectGrid has a built in timed based evictor that is referred to as "time to live" evictor or TTL evictor.
 

Exception Summary
ClientServerMultipleReplicationGroupMemberWriteTransactionCallbackException
This exception is thrown when a method call to the Client/Server TransactionCallback detects the user is attempting to perform a write against multiple maps in different Map Sets, Partition Sets or Replication groups.
ConnectException
This exception is used to indicate that the client was unable to connect to the server
DuplicateKeyException
A DuplicateKeyException exception is thrown if a key cannot be inserted into a BackingMap because an object with the same key already exists.
KeyNotFoundException
Normally, record not found means a null is returned.
LockDeadlockException
This exception is used by the lock manager to indicate that it detected a deadlock.
LockException
A general locking exception indicating something went wrong with locking operations.
LockInternalFailureException
This exception is used by the lock manager to indicate it detected some internal programming error while processing a lock or unlock request.
LockTimeoutException
This exception is used by the lock manager to indicate that the maximum wait time for a lock has been exceeded.
NoActiveTransactionException
An exception indicating there is no active transaction.
ObjectGridException
Base exception class for all checked exceptions thrown by the ObjectGrid product.
ObjectGridRuntimeException
This exception is the base class for all runtime exceptions thrown by the cache.
ReadOnlyException
This exception is thrown when an attempt is made to modifying operations on a read only maps.
ReplicationVotedToRollbackTransactionException
This exception is thrown when a transaction was rolled back because some/all of the replicas failed to apply the transaction when in synchronous replication mode.
SessionNotReentrantException
A Session object can only be used by a single thread concurrently to perform map operations.
TargetNotAvailableException
A TargetNotAvailableException indicates the ObjectGrid target is not available.
TransactionAffinityException
This exception is thrown for inflight transaction when server fails over.
TransactionAlreadyActiveException
An exception indicating a transaction is already active for the current session.
TransactionException
A general transaction exception indicating something went wrong with a transaction.
TransactionQuiesceException
This exception is thrown when partition/shard/mapset/replication group/ replication group member/server/cluster/objectgrid is entered quiesce process for various reasons such as shard movement, partition relocation, system update, server shutdown, and others.
TransactionTimeoutException
This exception is thrown when a transaction exceeds the transaction timeout that was specified on the ObjectGrid or Session.
UnavailableServiceException
This exception is thrown when all servers are dead or when all services are unavailable even though servers are running.
UndefinedMapException
This exception indicates that the map which an application tries to access is not defined in the ObjectGrid.
 


Package com.ibm.websphere.objectgrid Description

These are the main application APIs for the ObjectGrid. The main interface here is the ObjectGrid interface. A JVM needs to create at least one instance.


Introduction

The WebSphere ObjectGrid is designed as a data caching tier that can be used to hold data from multiple sources and then make it available to the clients of the ObjectGrid. The clients access the data through the ObjectGrid APIs. The ObjectGrid is designed to be able to store large quantities of data.


Programming Tutorial

The following sections show snippets on the usage of the ObjectGrid APIs.


Obtaining a ObjectGrid instance.

The application needs to construct an ObjectGrid reference first. An application can choose to make several ObjectGrid instances. Each instance is independent, however, and has it's own configuration file. For now, use the following code and programmatically initialize it using the setter methods on the ObjectGrid.

ObjectGrid objectGrid = new ObjectGridImpl();

The instance can then have a Map defined on it using the following snippet:

BackingMap bm = objectGrid.defineMap("table1");

Again, setter methods on BackingMap allow it to be configured once it's defined.


Working with an ObjectGrid, Sessions

Each thread that wants to access the ObjectGrid must have its own Session instance. The ObjectGrid class has a getSession method that returns one. Once the thread has a Session then it can obtain ObjectMap instances for manipulating data in the ObjectGrid as well as use the begin/commit/rollback methods on the Session to handle transactions.

Session session = objectGrid.getSession();
ObjectMap table1 = session.getMap("table1");
session.begin();
MyData d = (MyData)table1.get("key1");
session.commit();


Package com.ibm.websphere.objectgrid.client

This package contains the primary interfaces and classes for setting behaviors for ObjectGrid clients for this process.

See:
          Description

Interface Summary
ClientProperties
The set of properties used to define various preference for ObjectGrid clients.
 


Package com.ibm.websphere.objectgrid.client Description

This package contains the primary interfaces and classes for setting behaviors for ObjectGrid clients for this process.


Overview

The interfaces in this package should not be implemented directly but are used by the ClientClusterContext to set default behaviors for application clients for an ObjectGrid instance. http://publib.boulder.ibm.com/infocenter/wdpxc/v2r0/topic/com.ibm.websphere.datapower.xc.javadoc.doc/topics/

The properties available for use are defined in the ClientProperties.html" >ClientProperties interface.

There are two ways to configure client properties:

  1. Create a properties file named objectGridClient.properties and store it in the root of your classpath.
  2. Create a properties file on your file system in the directory where the client is started from named objectGridClient.properties.
  3. Create a properties file with any path and name and use the following system property to detect it: -Dcom.ibm.websphere.objectgrid.ClientProperties=<fileName>
  4. Create a properties file with any path and name and set load it programmatically and pass url to ClientClusterContext.getClientProperties(ogname, url).
  5. Programmatically define the properties the ClientProperties set methods.

In the following example we set the proximity routing defaults for all clients that use this ClientClusterContext: 

    ObjectGridManager ogMgr = ObjectGridManagerFactory.getObjectGridManager();
    ClientClusterContext ccc = ogMgr.connect(...);
    ClientProperties props = ccc.getClientProperties("myOGName");
    props.setPreferLocalHost(true);
    props.setPreferLocalProcess(true);
    props.setPreferZones(new String[]{"New York", "Texas"});

    // The ClientProperites are now applied to the ObjectGrid client connection:
    ObjectGrid og=ogMgr.get(ccc, "myOGName");
The following example uses a custom client properties file: 

    ClientClusterContext ccc = ogMgr.connect(...);
    URL clientPropsURL = Thread.currentThread().getContextClassLoader().getResource("etc/myObjectGridClient.properties");
    ClientProperties props = ccc.setClientProperties("myOGName", clientPropsURL);

    // The ClientProperites are now applied to the ObjectGrid client connection:
    ObjectGrid og=ogMgr.get(ccc, "myOGName");
The following file is an example of a properties file that matches the proceeding API: 

    preferLocalProcess=true
    preferLocalhost=true
    preferZones=New York,Texas


com.ibm.websphere.objectgrid.client
Interface ClientProperties

public interface ClientProperties

The set of properties used to define various preference for ObjectGrid clients.

See the package summary for details on how to use the ClientProperties class and properties file.

Since:
WAS XD 6.1.0.3, XC10

Field Summary
static java.lang.String CLIENT_PROPS_FILE_PATH_KEY
          The system property key to override the location of the client properties file.
static java.lang.String CLIENTPROPERTIESFILEPATHKEY
          Deprecated. The CLIENTPROPERTIESFILEPATHKEY is deprecated in version 7.0. Use the CLIENT_PROPS_FILE_PATH_KEY property.
static java.lang.String DEFAULTCLIENTPROPERTYFILE
          The default name of client property file
static java.lang.String PROP_LISTENER_HOST
          Listener host property key for the client properties file.
static java.lang.String PROP_LISTENER_PORT
          Listener port property key for the client properties file.
static java.lang.String PROP_PREFER_LOCAL_HOST
          Currently, this property is not used.
static java.lang.String PROP_PREFER_LOCAL_PROCESS
          Currently, this property is not used.
static java.lang.String PROP_PREFER_ZONES
          Prefer zones property key for the client properties file.
static java.lang.String PROP_REQUEST_RETRY_TIMEOUT
          The requestRetryTimeout which indicates how long to retry a request (in milliseconds).
static java.lang.String PROP_SHUFFLE_BOOTSTRAP_ADDRESSES
          The shuffleBoostrapAddresses property is used to determine if the catalog service grid addresses should be randomized when used by a client when bootstrapping to the grid.
 
Method Summary
java.lang.String getListenerHost()
          Retrieves the host to be used by the ORB.
int getListenerPort()
          Retrieves the port to be used by the ORB.
java.lang.String[] getPreferZones()
          Retrieve the preferred zones.
long getRequestRetryTimeout()
          Retrieves the current request retry timeout.
boolean isBootStrapListShuffled()
          Retrieves the value of the BootStrapListShuffled property.
boolean isPreferLocalHost()
          This method is reserved for future use.
boolean isPreferLocalProcess()
          This method is reserved for future use.
void setBootStrapListShuffled(boolean shuffle)
          Sets the value of the BootStrapListShuffled property.
void setPreferLocalHost(boolean localHost)
          This method is reserved for future use.
void setPreferLocalProcess(boolean localProcess)
          This method is reserved for future use.
void setPreferZones(java.lang.String[] zones)
          Prefer routing to specific zones.
void setRequestRetryTimeout(long requestRetryTimeout)
          Set the request retry timeout to indicate how long to retry a request (in milliseconds) when recoverable failures occur, such as fail-over exceptions.
 

Field Detail

DEFAULTCLIENTPROPERTYFILE

static final java.lang.String DEFAULTCLIENTPROPERTYFILE

The default name of client property file

CLIENTPROPERTIESFILEPATHKEY

static final java.lang.String CLIENTPROPERTIESFILEPATHKEY

Deprecated. The CLIENTPROPERTIESFILEPATHKEY is deprecated in version 7.0. Use the CLIENT_PROPS_FILE_PATH_KEY property.
The deprecated system property key to override the location of the client properties file.

CLIENT_PROPS_FILE_PATH_KEY

static final java.lang.String CLIENT_PROPS_FILE_PATH_KEY

The system property key to override the location of the client properties file. This property is used to replace the CLIENTPROPERTIESFILEPATHKEY

Since:
7.0

PROP_PREFER_LOCAL_PROCESS

static final java.lang.String PROP_PREFER_LOCAL_PROCESS

Currently, this property is not used. It is reserved for future use.

Constant Field Values

PROP_PREFER_LOCAL_HOST

static final java.lang.String PROP_PREFER_LOCAL_HOST

Currently, this property is not used. It is reserved for future use.

Constant Field Values

PROP_PREFER_ZONES

static final java.lang.String PROP_PREFER_ZONES

Prefer zones property key for the client properties file. Each specified zone is separated by a comma in the form: preferZones=ZoneA,ZoneB,ZoneC

Constant Field Values

PROP_REQUEST_RETRY_TIMEOUT

static final java.lang.String PROP_REQUEST_RETRY_TIMEOUT

The requestRetryTimeout which indicates how long to retry a request (in milliseconds). A 0 indicates that the request should fail fast and skip over in internal retry logic. Exceptions that cannot succeed even if tried again such as DuplicateException will be returned immediately.

Since:
7.0
Constant Field Values

PROP_LISTENER_HOST

static final java.lang.String PROP_LISTENER_HOST

Listener host property key for the client properties file.

Since:
XS 7.1
Constant Field Values

PROP_LISTENER_PORT

static final java.lang.String PROP_LISTENER_PORT

Listener port property key for the client properties file.

Since:
XS 7.1
Constant Field Values

PROP_SHUFFLE_BOOTSTRAP_ADDRESSES

static final java.lang.String PROP_SHUFFLE_BOOTSTRAP_ADDRESSES

The shuffleBoostrapAddresses property is used to determine if the catalog service grid addresses should be randomized when used by a client when bootstrapping to the grid. The default value of the property is true.

Since:
7.1.0.3
Method Detail

setPreferZones

void setPreferZones(java.lang.String[] zones)

Prefer routing to specific zones.

When zones are enabled on an ObjectGrid, requests will be routed to the specified zones.

Parameters:
zones - array of zone names. If null or an empty array, then requests are routed to all zones.

setPreferLocalProcess

void setPreferLocalProcess(boolean localProcess)

This method is reserved for future use. Calls to the method will not result in any performed operation.

Parameters:
localProcess -

setPreferLocalHost

void setPreferLocalHost(boolean localHost)

This method is reserved for future use. Calls to the method will not result in any performed operation.

Parameters:
localHost -

getPreferZones

java.lang.String[] getPreferZones()

Retrieve the preferred zones.

Returns:
the preferred zones.

isPreferLocalProcess

boolean isPreferLocalProcess()

This method is reserved for future use. The returned value should be ignored by the user.

Returns:
false

isPreferLocalHost

boolean isPreferLocalHost()

This method is reserved for future use. The returned value should be ignored by the user.

Returns:
false

setRequestRetryTimeout

void setRequestRetryTimeout(long requestRetryTimeout)

Set the request retry timeout to indicate how long to retry a request (in milliseconds) when recoverable failures occur, such as fail-over exceptions. A request will timeout when either the request timeout expires or the transaction timeout expires, whichever expires first.

A value of 0 indicates that all requests should fail immediately and avoid any retry logic. Exceptions that cannot succeed even if tried again such as DuplicateKeyException exceptions will be thrown immediately.

A value of -1 indicates that the request retry timeout is not set, meaning that the request duration is governed by the transaction timeout.

The request retry timeout can be overridden using the Session.setRequestRetryTimeout(long) method.

Parameters:
requestRetryTimeout - the duration in milliseconds retry a client request, 0 if the request should fail immediately or -1 if the request timeout is not set.

Since:
7.0
ObjectGrid.setTxTimeout(int)

getRequestRetryTimeout

long getRequestRetryTimeout()

Retrieves the current request retry timeout. Returns -1 if it was not set.

Returns:
requestRetryTimeout in milliseconds, 0 to fail immediately or -1 if not set.

Since:
7.0

getListenerHost

java.lang.String getListenerHost()

Retrieves the host to be used by the ORB. The listener host property defaults to 'localhost'. This property can only be set in the client.properties file.

Returns:
The host that the ORB will bind to.

Since:
7.1

getListenerPort

int getListenerPort()

Retrieves the port to be used by the ORB. The listener port property defaults to the corbaloc port, 2809. This property can only be set in the client.properties file.

Returns:
The port that the ORB will bind to.

Since:
7.1

isBootStrapListShuffled

boolean isBootStrapListShuffled()

Retrieves the value of the BootStrapListShuffled property.

Returns:
true if the value of BootStrapListeShuffled was set to true. false if the value of BootStrapListeShuffled was set to false.

Since:
7.1.0.3

setBootStrapListShuffled

void setBootStrapListShuffled(boolean shuffle)

Sets the value of the BootStrapListShuffled property.

Parameters:
shuffle - true the bootstrap list will be shuffled providing each client a random distribution of catalog servers to select from. false the first viable address in the list of catalog servers will be used.

Since:
7.1.0.3


Package com.ibm.websphere.objectgrid.spring

This package holds the Spring specific APIs for ObjectGrid.

See:
          Description

Interface Summary
SpringLocalTxManager
This interface has the methods for interacting with the ObjectGrid Spring LocalTransactionManager.
 

Class Summary
ObjectGridSpringFactory
This class serves as a factory to construct instances of the various Spring specific APIs.
 

Exception Summary
CannotGetObjectGridSessionException
This can be thrown by getSession if a new Session cannot be obtained for any reason.
ObjectGridTransactionException
The ObjectGrid platform transaction manager can throw this unchecked exception whenever errors occur.
 


Package com.ibm.websphere.objectgrid.spring Description

This package holds the Spring specific APIs for ObjectGrid.


Local Transaction Support

ObjectGrid has implemented a Spring PlatformTransactionManager. This allows Spring to manage local transactions using a single ObjectGrid session. Spring can then be used to annotate POJOs with container managed transaction semantics much like a J2EE application server does using J2EE CMT. An application should instantiate a SpringLocalTxManager using the appropriate factory method on ObjectGridSpringFactory and then wire a reference to that object in to all POJOs that use Spring CMT. This instance has a getSession method to obtain the correct Session for that POJO. The application must call one of the SpringLocalTxManager#setObjectGridForThread methods before invoking a managed POJO to specify which ObjectGrid instance should be used for any CMT on this thread.


com.ibm.websphere.objectgrid.spring
Class CannotGetObjectGridSessionException

java.lang.Object
  ava.lang.Throwable
      ava.lang.Exception
          ava.lang.RuntimeException
              org.springframework.core.NestedRuntimeException
                  com.ibm.websphere.objectgrid.spring.CannotGetObjectGridSessionException

All Implemented Interfaces:
java.io.Serializable

public class CannotGetObjectGridSessionException


extends org.springframework.core.NestedRuntimeException

This can be thrown by getSession if a new Session cannot be obtained for any reason.

Since:
WAS XD 6.1 FIX3, XC10

Constructor Summary
CannotGetObjectGridSessionException(java.lang.String message)
          Constructs a new CannotGetObjectGridSessionException with the specified detail message.
CannotGetObjectGridSessionException(java.lang.String message, java.lang.Throwable cause)
          Constructs a new CannotGetObjectGridSessionException with the specified detail message and cause.
 
Method Summary
 
Methods inherited from class org.springframework.core.NestedRuntimeException

contains, getMessage, getMostSpecificCause, getRootCause
 
Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
 
Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

CannotGetObjectGridSessionException

public CannotGetObjectGridSessionException(java.lang.String message,
                                           java.lang.Throwable cause)

Constructs a new CannotGetObjectGridSessionException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this CannotGetObjectGridSessionException's detail message.

Parameters:
message - the detail message (which is saved for later retrieval by the getMessage method).
cause - the cause (which is saved for later retrieval by the getCause method). (Anull value is permitted, and indicates that the cause is nonexistent or unknown). NestedRuntimeException.getMessage()

CannotGetObjectGridSessionException

public CannotGetObjectGridSessionException(java.lang.String message)

Constructs a new CannotGetObjectGridSessionException with the specified detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

Parameters:
message - the detail message. The detail message is saved for later retrieval by the getMessage method. NestedRuntimeException.getMessage()


com.ibm.websphere.objectgrid.spring
Class ObjectGridSpringFactory

java.lang.Object
  com.ibm.websphere.objectgrid.spring.ObjectGridSpringFactory


public final class ObjectGridSpringFactory


extends java.lang.Object

This class serves as a factory to construct instances of the various Spring specific APIs.

Since:
WAS XD 6.1 FIX3, XC10

Field Summary
static java.lang.String SCOPE_SHARD
          Scope identifier for shard scope: "shard".
 
Constructor Summary
ObjectGridSpringFactory()
           
 
Method Summary
static BeanFactory getBeanFactoryForObjectGrid(java.lang.String objectGridName)
          This returns the currently registered external bean factory for a named object grid.
static java.lang.Object getBeanInShardScope(ObjectGrid shard, java.lang.String beanName)
          This returns an instance of the named Spring bean with the current shard scope using the specified ObjectGrid instance.
static SpringLocalTxManager getLocalPlatformTransactionManager()
          This returns an ObjectGrid PlatformLocalTransactionManager.
static void registerSpringBeanFactoryAdapter(java.lang.String objectGridName, java.lang.Object springBeanFactory)
          This returns an adapter for a Spring based bean factory.
 
Methods inherited from class java.lang.Object

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

Field Detail

SCOPE_SHARD

public static final java.lang.String SCOPE_SHARD

Scope identifier for shard scope: "shard".

Constant Field Values
Constructor Detail

ObjectGridSpringFactory

public ObjectGridSpringFactory()

Method Detail

getLocalPlatformTransactionManager

public static SpringLocalTxManager getLocalPlatformTransactionManager()

This returns an ObjectGrid PlatformLocalTransactionManager.

Returns:
the PlatformLocalTransactionManager instance.

registerSpringBeanFactoryAdapter

public static void registerSpringBeanFactoryAdapter(java.lang.String objectGridName,
                                                    java.lang.Object springBeanFactory)
                                             throws java.lang.ClassCastException

This returns an adapter for a Spring based bean factory. We use an Object type here to avoid making ObjectGrid dependent on Spring classes being present. A ClassCastException exception is thrown if the supplied factory isn't a Spring BeanFactory instance.

Parameters:
objectGridName - the name of the ObjectGrid
springBeanFactory - A Spring BeanFactory instance.

Throws:
java.lang.ClassCastException - thrown when the Object type is not a BeanFactory instance.

getBeanFactoryForObjectGrid

public static BeanFactory getBeanFactoryForObjectGrid(java.lang.String objectGridName)

This returns the currently registered external bean factory for a named object grid. If no factory has been registered then it attempts to construct a Spring BeanFactory using the xml resource on the class path @ "/X_spring.xml" and /META-INF/X_spring.xml where X is the name of the ObjectGrid. If the xml file is on the class path then the ObjectGrid name MUST be a valid resource name.

Parameters:
objectGridName - The name of the ObjectGrid

Returns:
The BeanFactory instance or null if there were none registered

getBeanInShardScope

public static java.lang.Object getBeanInShardScope(ObjectGrid shard,
                                                   java.lang.String beanName)

This returns an instance of the named Spring bean with the current shard scope using the specified ObjectGrid instance. This allows shard scoped beans to be obtained.

Parameters:
shard - The ObjectGrid instance to use to scope Spring beans using "shard" as scope.
beanName - The bean to return

Returns:
The bean instance if it exists


com.ibm.websphere.objectgrid.spring
Class ObjectGridTransactionException

java.lang.Object
  ava.lang.Throwable
      ava.lang.Exception
          ava.lang.RuntimeException
              org.springframework.core.NestedRuntimeException
                  org.springframework.transaction.TransactionException
                      com.ibm.websphere.objectgrid.spring.ObjectGridTransactionException

All Implemented Interfaces:
java.io.Serializable

public class ObjectGridTransactionException


extends org.springframework.transaction.TransactionException

The ObjectGrid platform transaction manager can throw this unchecked exception whenever errors occur.

Since:
WAS XD 6.1 FIX3, XC10

Constructor Summary
ObjectGridTransactionException(java.lang.String message)
          Constructs a new ObjectGridTransactionException with the specified detail message.
ObjectGridTransactionException(java.lang.String message, java.lang.Throwable cause)
          Constructs a new ObjectGridTransactionException with the specified detail message and cause.
 
Method Summary
 
Methods inherited from class org.springframework.core.NestedRuntimeException

contains, getMessage, getMostSpecificCause, getRootCause
 
Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
 
Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ObjectGridTransactionException

public ObjectGridTransactionException(java.lang.String message,
                                      java.lang.Throwable cause)

Constructs a new ObjectGridTransactionException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this ObjectGridTransactionException's detail message.

Parameters:
message - the detail message (which is saved for later retrieval by the getMessage method).
cause - the cause (which is saved for later retrieval by the getCause method). (Anull value is permitted, and indicates that the cause is nonexistent or unknown). NestedRuntimeException.getMessage()

ObjectGridTransactionException

public ObjectGridTransactionException(java.lang.String message)

Constructs a new ObjectGridTransactionException with the specified detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

Parameters:
message - the detail message. The detail message is saved for later retrieval by the getMessage method. NestedRuntimeException.getMessage()


com.ibm.websphere.objectgrid.spring
Interface SpringLocalTxManager

public interface SpringLocalTxManager

This interface has the methods for interacting with the ObjectGrid Spring LocalTransactionManager. It also allows the desired partition to use with this thread to be specified.

Since:
WAS XD 6.1 FIX3, XC10

Method Summary
Session getSession()
          This returns a managed session for the ObjectGrid associated with this thread.
void setObjectGridForThread(ObjectGrid grid)
          This indicates the ObjectGrid to use on this thread when a session is requested.
 

Method Detail

setObjectGridForThread

void setObjectGridForThread(ObjectGrid grid)

This indicates the ObjectGrid to use on this thread when a session is requested. This replaces any previously associated ObjectGrid, i.e. only a single grid instance can be associated with a thread at a time.

Parameters:
grid - the ObjectGrid to set on this thread.

getSession

Session getSession()

This returns a managed session for the ObjectGrid associated with this thread.

Do not call begin, commit or rollback directly on the session. Spring manages the transaction automatically.

Returns:
A managed Session to use with this thread.

Throws:
CannotGetObjectGridSessionException - thrown when an ObjectGrid session can't be retrieved.


Package com.ibm.websphere.objectgrid.plugins

These are the interfaces for adding plugins to the Grid core framework.

See:
          Description

Interface Summary
BeanFactory
Implement this interface to allow bean factories like Spring or Google guice to be integrated.
CacheEntry
This interface represents a cache entry in an ObjectGrid map.
EvictionEventCallback
An instance of EvictionEventCallback is passed into the Evictor at initialization time.
Evictor
Data contained in a BackingMap are evicted when the map is full.
EvictorData
This interface is optionally used by an implementator of the Evictor interface.
LogElement
LogElements are the individual entries within a LogSequence.
LogSequence
LogSequence is the ordered list of changes performed against a given map for a given transaction.
LogSequenceFilter
This interface can be used to filter a LogSequence.
MapEventListener
This callback interface is implemented by the application when it wants to receive events about a Map such as the eviction of a map entry.
ObjectGridEventGroup
This is a set of single method interfaces for fine grained events delivered for an ObjectGrid.
ObjectGridEventGroup.ShardEvents
These events are fired when a shard is made a primary shard and when the shard is demoted from a primary.
ObjectGridEventGroup.ShardLifecycle
These events are fired when an ObjectGrid shard is initialized and destroyed.
ObjectGridEventGroup.TransactionEvents
These events are called every single transaction.
ObjectGridEventListener
This interface is used to create an implementation of an event listener for an ObjectGrid.
ReplicationMapListener
This interface is used to create an implementation of an event listener for client-side maps that are in replication mode.
TransactionCallback
Calling methods on a Session will send corresponding events to the TransactionCallback.
TransactionCallback.BeforeCommit
The BeforeCommit optional mix-in interface for the TransactionCallback plug-in interface allows plug-ins to be notified at the beginning of a Session.commit().
TransactionCallback.BeforeCommit.TransactionContext
The TransactionContext identifies various information that's available to the beforeCommit() method.
ValueProxyInfo
This interface can be used by value objects to inform a BackingMap or Loader which attribute(s) have been dirtied.
 

Class Summary
EvictorData.SpecialEvictorData
Special value class used for representing the key not being found in the BackingMap.
LogElement.Type
The Type class is used to represent a LogElement type.
 

Exception Summary
CacheEntryException
This exception indicates an error occurred during a cache entry operation.
LoaderException
This exception is the base exception for any exceptions encountered by a Loader.
TransactionCallbackException
This exception is thrown when a method call to TransactionCallback fails.
 


Package com.ibm.websphere.objectgrid.plugins Description

These are the interfaces for adding plugins to the Grid core framework.


Overview

These plugins can be added into ObjectGrid in several ways such as xml configuration, programmatically adding, or using annotation.


Annotation based callbacks

ObjectGrid when running on Java 5 will start to use an annotated method callback system. This means that objects can be registered as callbacks or listeners. The methods on the object must be annotated as to be invoked for a certain event. Unannotated methods are not invoked. The name of the method is unimportant. The method arguments and return type must be the same as expected for the callback method.

Why?

Usually, callbacks are specified using an interface. This works well but results in a possible performance loss as all methods on the interface will be invoked by the ObjectGrid even though the application is only interested in a single event. This wastes precious resources. Another issue is when we need to add a new event. Adding a new method to an existing interface breaks back wards compatibility. We can make a new interface extending the old one with the new methods but this is also undesirable as soon there are many interfaces in the hierarchy as new events are added. The annotation system allows the application to only mark methods to be called avoiding the first problem and if new event types are added they have no impact on existing callback objects. Newer applications can add a method and annotate it with the new event annotation to receive the event.


Package com.ibm.websphere.objectgrid.plugins.builtins

This package contains built-in plugins for ObjectGrid core.

See:
          Description

Class Summary
LFUEvictor
This class manages a BackingMap using a simple Least Frequently Used (LFU) algorithm.
LRUEvictor
This evictor manages a BackingMap using a simple Least Recently Used (LRU) algorithm.
WebSphereTransactionCallback
A TransactionCallback plugin used to automatically enlist the ObjectGrid transaction as a volatile participant in a WebSphere JTA transaction.
 


Package com.ibm.websphere.objectgrid.plugins.builtins Description

This package contains built-in plugins for ObjectGrid core.


Overview

These built-in plugins can be used to configure ObjectGrid to achieve desired functions.


com.ibm.websphere.objectgrid.plugins.builtins
Class LFUEvictor

java.lang.Object
  b>com.ibm.websphere.objectgrid.plugins.builtins.LFUEvictor

All Implemented Interfaces:
Evictor, RollbackEvictor, java.lang.Runnable

public final class LFUEvictor


extends java.lang.Object


implements Evictor, RollbackEvictor, java.lang.Runnable

This class manages a BackingMap using a simple Least Frequently Used (LFU) algorithm. It attempts to keep the BackingMap at less than a certain number of entries based on a usage count of each entry. This class uses an array of binary heap objects for keeping a EvictorData object created for a CacheEntry. The EvictorData object has the LFU count and key for the CacheEntry. The idea is to spread cache entries across multiple binary heap objects so that there are fewer CacheEntry objects that collide on a synchronization point since they all do not use the same binary heap object.

An evictor thread is spawned during initialization that wakes up periodically and processes the array of binary heap objects to determine if any CacheEntry needs to be evicted. The idea of using a binary heap object is to obtain an ordering by LFU value so that it is not necessary to enumerate over every CacheEntry to determine if it needs to be evicted. Since binary heap is a partial ordering, the cost to do the ordering is cheaper than creating a totally ordered list and/or sorting the list. But it also means the LFU algorithm is not 100% accurate, but it is close enough to be useful and avoids the cost of being 100% accurate by keep a totally ordered list.

Since:
WAS XD 6.0, XC10

Field Summary
static int DEFAULT_NUMBER_OF_HEAPS
          Default number of binary heaps to create if the setNumberOfHeaps(int) method is not called.
static long DEFAULT_SLEEP_TIME
          Default sleep time for evictor thread if the setSleepTime(int) method is not called.
 
Constructor Summary
LFUEvictor()
          Creates a LFUEvictor object with default values for the maximum size per heap, the number of heaps, and sleep time between sweeps of the heaps by the evictor thread.
 
Method Summary
void activate()
          This method is called to activate the Evictor.
void apply(LogSequence sequence)
          Called after a transaction has committed to allow the evictor to track object usage in the BackingMap.
void deactivate()
          This method is called to deactivate the Evictor.
void destroy()
          Called when the BackingMap associated with this evictor is destroyed.
int getMaxSize()
          Gets the maximum size of each binary heap.
int getNumberOfHeaps()
          Gets number of binary heaps being used.
int getSleepTime()
          Gets the sleep time being used in seconds.
void initialize(BackingMap map, EvictionEventCallback callback)
          Called by a BackingMap instance during the evictor initialization time.
void rollingBack(LogSequence sequence)
           
void run()
          Periodically wakes up and evicts entries.
void setMaxSize(int maxSize)
          Sets the maximum size of each binary heap.
void setNumberOfHeaps(int numberOfHeaps)
          Sets the number of binary heaps to use.
void setSleepTime(int seconds)
          Sets the sleep time to use in seconds.
 
Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_SLEEP_TIME

public static final long DEFAULT_SLEEP_TIME

Default sleep time for evictor thread if the setSleepTime(int) method is not called.

Constant Field Values

DEFAULT_NUMBER_OF_HEAPS

public static final int DEFAULT_NUMBER_OF_HEAPS

Default number of binary heaps to create if the setNumberOfHeaps(int) method is not called.

Constant Field Values
Constructor Detail

LFUEvictor

public LFUEvictor()

Creates a LFUEvictor object with default values for the maximum size per heap, the number of heaps, and sleep time between sweeps of the heaps by the evictor thread.

The default values can be overridden by use of the setMaxSize(int), setNumberOfHeaps(int), and setSleepTime(int) methods. If the setMaxSize method is never called, the size of the map is unlimited.

DEFAULT_SLEEP_TIME, setMaxSize(int), setNumberOfHeaps(int), setSleepTime(int)
Method Detail

getMaxSize

public int getMaxSize()

Gets the maximum size of each binary heap.

Returns:
the same value that was passed to the setMaxSize(int) method or the default value of zero if the setMaxSize method is never called

destroy

public void destroy()

Description copied from interface: Evictor

Called when the BackingMap associated with this evictor is destroyed.

This method is the opposite of the initialize method. When it is called, the Evictor can free up any resources it uses.

Specified by:
destroy in interface Evictor

initialize

public void initialize(BackingMap map,
                       EvictionEventCallback callback)

Description copied from interface: Evictor

Called by a BackingMap instance during the evictor initialization time.

The BackingMap calls this method so the Evictor instance can have references to the BackingMap and EvictionEventCallback instances. The evictor can signal events to have specific entries evicted using the EvictionEventCallback.

Specified by:
initialize in interface Evictor

Parameters:
map - the BackingMap instance
callback - the EvictionEventCallback instance

apply

public void apply(LogSequence sequence)

Description copied from interface: Evictor
Called after a transaction has committed to allow the evictor to track object usage in the BackingMap.

This method also reports any entries that have been successfully evicted. Note, this method is not called for transactions that are rolled back. If there is a need to track object usage for rolled back transactions, the evictor must implement the RollbackEvictor interface as well.

This method is called after a transaction has completed. Consequently, all transaction locks that were acquired by the completed transaction are no longer held. Potentially, multiple threads could call this method concurrently and each thread would be completing its own transaction. Since transaction locks are already released by the completed transaction, this method must provide its own synchronization to ensure it is thread safe. For an Evictor in an ObjectMap configured to use a KeySerializerPlugin or ValueSerializerPlugin, the keys and values objects in the LogSequence will be SerializedKey or SerializedValue objects respectively. If required, you can use the SerializedEntry.getObject() method to retrieve (possibly inflating the serialized object) the original key or value object.

Specified by:
apply in interface Evictor

Parameters:
sequence - the LogSequence of changes committed to the map

rollingBack

public void rollingBack(LogSequence sequence)

Specified by:
rollingBack in interface RollbackEvictor

getNumberOfHeaps

public int getNumberOfHeaps()

Gets number of binary heaps being used.

Returns:
the same value that was passed to the setNumberOfHeaps(int) method or the default value of DEFAULT_NUMBER_OF_HEAPS if the setNumberOfHeaps method is never called setNumberOfHeaps(int)

setNumberOfHeaps

public void setNumberOfHeaps(int numberOfHeaps)

Sets the number of binary heaps to use.

This method is used to override the default number of binary heaps created by the initialize method for keeping the usage count data needed by the evictor thread. This method must be called prior to the initialize method to avoid an IllegalStateException being thrown. If this method is not called,the DEFAULT_NUMBER_OF_HEAPS constant is used as the number of heaps.

Parameters:
numberOfHeaps - is the number of BinaryHeap instances used to hold entry usage count data. The value must be greater than or equal to 1 and a prime number is recommended for best performance.

Throws:
java.lang.IllegalArgumentException - if numberOfHeaps < 1
java.lang.IllegalStateException - if called after the initialize method. initialize(BackingMap, EvictionEventCallback)

getSleepTime

public int getSleepTime()

Gets the sleep time being used in seconds.

Returns:
the same value that was passed to the setSleepTime(int) method or the default value of DEFAULT_SLEEP_TIME if the setSleepTime method is never called

setSleepTime

public void setSleepTime(int seconds)

Sets the sleep time to use in seconds.

This method is used to override the default sleep time of the evictor thread in seconds. This method must be called prior to the initialize method to avoid an IllegalStateException being thrown. If this method is not called, the DEFAULT_SLEEP_TIME constant is used as the sleep time.

Parameters:
seconds - is the number of seconds the evictor thread sleeps in between each sweep of the binary heap data being kept for entry usage count data.

Throws:
java.lang.IllegalArgumentException - if seconds < 1
java.lang.IllegalStateException - if called after the initialize method. initialize(BackingMap, EvictionEventCallback)

setMaxSize

public void setMaxSize(int maxSize)

Sets the maximum size of each binary heap.

This method is used to override the default maximum size for each heap used to keep entry usage count data. The evictor thread will attempt to keep each heap to be no larger than the maximum size. This method must be called prior to the initialize method to avoid an IllegalStateException being thrown.

Parameters:
maxSize - is the maximum size per heap. Any value <= 0 indicates to allow each heap to be of unlimited size. In which case, no entry usage count data is kept.

Throws:
java.lang.IllegalStateException - if called after the initialize method.

run

public void run()

Periodically wakes up and evicts entries.

Specified by:
run in interface java.lang.Runnable

activate

public void activate()

Description copied from interface: Evictor
This method is called to activate the Evictor. Until this method is called, the Evictor must not use the EvictionEventCallback interface to evict any map entries. If it does use the EvictionEventcallback interface to evict map entries prior to activate being called, an IllegalStateException is thrown.

Specified by:
activate in interface Evictor

deactivate

public void deactivate()

Description copied from interface: Evictor
This method is called to deactivate the Evictor. Once this method is called, the Evictor must quit using the EvictionEventCallback interface to evict any map entries. If it does use the EvictionEventcallback interface after this method is called, an IllegalStateException is thrown.

Specified by:
deactivate in interface Evictor


com.ibm.websphere.objectgrid.plugins.builtins
Class LRUEvictor

java.lang.Object
  b>com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor

All Implemented Interfaces:
Evictor, RollbackEvictor, java.lang.Runnable

public final class LRUEvictor


extends java.lang.Object


implements Evictor, RollbackEvictor, java.lang.Runnable

This evictor manages a BackingMap using a simple Least Recently Used (LRU) algorithm. It attempts to keep the BackingMap at less than a certain number of entries.

Since:
WAS XD 6.0, XC10

Field Summary
static int DEFAULT_NUMBER_OF_QUEUES
          Default number of LRU queues to create if the setNumberOfLRUQueues(int) method is not called.
static long DEFAULT_SLEEP_TIME
          Default sleep time for evictor thread if the setSleepTime(int) method is not called.
 
Constructor Summary
LRUEvictor()
          Creates a new LRUEvictor object with default values for the maximum size per LRU queue, the number of queues, and sleep time between sweeps by the evictor thread.
 
Method Summary
void activate()
          This method is called to activate the Evictor.
void apply(LogSequence sequence)
          Maintains a bi-directional queue ordered on last access.
void deactivate()
          This method is called to deactivate the Evictor.
void destroy()
          Called when the BackingMap associated with this evictor is destroyed.
int getMaxSize()
          Gets the maximum size of each LRU queue.
int getNumberOfLRUQueues()
          Gets number of LRU queues being used.
int getSleepTime()
          Gets the sleep time being used in seconds.
void initialize(BackingMap map, EvictionEventCallback callback)
          Called by a BackingMap instance during the evictor initialization time.
void rollingBack(LogSequence sequence)
           
void run()
          Manages the map's size and sends eviction events to the Map.
void setMaxSize(int maxSize)
          Sets the maximum size of each LRU queue.
void setNumberOfLRUQueues(int numberOfQueues)
          Sets the number of LRU queues to use.
void setSleepTime(int seconds)
          Sets the sleep time to use in seconds.
 
Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_SLEEP_TIME

public static final long DEFAULT_SLEEP_TIME

Default sleep time for evictor thread if the setSleepTime(int) method is not called.

Constant Field Values

DEFAULT_NUMBER_OF_QUEUES

public static final int DEFAULT_NUMBER_OF_QUEUES

Default number of LRU queues to create if the setNumberOfLRUQueues(int) method is not called.

Constant Field Values
Constructor Detail

LRUEvictor

public LRUEvictor()

Creates a new LRUEvictor object with default values for the maximum size per LRU queue, the number of queues, and sleep time between sweeps by the evictor thread.

The default values can be overridden by use of the setMaxSize(int), setNumberOfLRUQueues(int), and setSleepTime(int) methods. If the setMaxSize method is never called, the size of BackingMap is unlimited and no LRU data is kept.

Method Detail

initialize

public void initialize(BackingMap map,
                       EvictionEventCallback callback)

Description copied from interface: Evictor

Called by a BackingMap instance during the evictor initialization time.

The BackingMap calls this method so the Evictor instance can have references to the BackingMap and EvictionEventCallback instances. The evictor can signal events to have specific entries evicted using the EvictionEventCallback.

Specified by:
initialize in interface Evictor

Parameters:
map - the BackingMap instance
callback - the EvictionEventCallback instance

apply

public void apply(LogSequence sequence)

Maintains a bi-directional queue ordered on last access.

Specified by:
apply in interface Evictor

Parameters:
sequence - the LogSequence of changes committed to the map

rollingBack

public void rollingBack(LogSequence sequence)

Specified by:
rollingBack in interface RollbackEvictor

getMaxSize

public int getMaxSize()

Gets the maximum size of each LRU queue.

Returns:
the same value that was passed to the setMaxSize(int) method or the default value of zero if the setMaxSize method is never called

setMaxSize

public void setMaxSize(int maxSize)

Sets the maximum size of each LRU queue.

This method is used to override the default maximum size for each LRU queue used to keep LRU data. The evictor thread will attempt to keep each LRU queue to be no larger than the maximum size. This method must be called prior to the initialize method to avoid an IllegalStateException being thrown.

Parameters:
maxSize - is the maximum size per LRU queue. Any value <= 0 indicates to allow each queue to be of unlimited size. In which case, no LRU data is kept.

Throws:
java.lang.IllegalStateException - if called after the initialize method.

getSleepTime

public int getSleepTime()

Gets the sleep time being used in seconds.

Returns:
the same value that was passed to the setSleepTime(int) method or the default value of DEFAULT_SLEEP_TIME if the setSleepTime method is never called

setSleepTime

public void setSleepTime(int seconds)

Sets the sleep time to use in seconds.

This method is used to override the default sleep time of the evictor thread in seconds. This method must be called prior to the initialize method to avoid an IllegalStateException being thrown. If this method is not called, the DEFAULT_SLEEP_TIME constant is used as the sleep time.

Parameters:
seconds - is the number of seconds the evictor thread sleeps in between each sweep of the LRU queue data

Throws:
java.lang.IllegalArgumentException - if seconds < 1
java.lang.IllegalStateException - if called after the initialize method. initialize(BackingMap, EvictionEventCallback)

getNumberOfLRUQueues

public int getNumberOfLRUQueues()

Gets number of LRU queues being used.

Returns:
the same value that was passed to the setNumberOfLRUQueues(int) method or the default value of DEFAULT_NUMBER_OF_QUEUES if the setNumberOfLRUQueues method is never called setNumberOfLRUQueues(int)

setNumberOfLRUQueues

public void setNumberOfLRUQueues(int numberOfQueues)

Sets the number of LRU queues to use.

This method is used to override the default number of LRU queues created by the initialize method for keeping the LRU data needed by the evictor thread. This method must be called prior to the initialize method to avoid an IllegalStateException being thrown. If this method is not called,the DEFAULT_NUMBER_OF_QUEUES constant is used as the number of heaps.

Parameters:
numberOfQueues - is the number of LRU queue instances used to hold LRU data. The value must be greater than or equal to 1 and a prime number is recommended for best performance.

Throws:
java.lang.IllegalArgumentException - if numberOfQueuess < 1
java.lang.IllegalStateException - if called after the initialize method. initialize(BackingMap, EvictionEventCallback)

run

public void run()

Manages the map's size and sends eviction events to the Map.

The thread is only spawned if the map size is limited rather than unlimited in size (e.g. maxSize > 0 ).

Specified by:
run in interface java.lang.Runnable

destroy

public void destroy()

Description copied from interface: Evictor

Called when the BackingMap associated with this evictor is destroyed.

This method is the opposite of the initialize method. When it is called, the Evictor can free up any resources it uses.

Specified by:
destroy in interface Evictor

activate

public void activate()

Description copied from interface: Evictor
This method is called to activate the Evictor. Until this method is called, the Evictor must not use the EvictionEventCallback interface to evict any map entries. If it does use the EvictionEventcallback interface to evict map entries prior to activate being called, an IllegalStateException is thrown.

Specified by:
activate in interface Evictor

deactivate

public void deactivate()

Description copied from interface: Evictor
This method is called to deactivate the Evictor. Once this method is called, the Evictor must quit using the EvictionEventCallback interface to evict any map entries. If it does use the EvictionEventcallback interface after this method is called, an IllegalStateException is thrown.

Specified by:
deactivate in interface Evictor


com.ibm.websphere.objectgrid.plugins.builtins
Class WebSphereTransactionCallback

java.lang.Object
  b>com.ibm.websphere.objectgrid.plugins.builtins.WebSphereTransactionCallback

All Implemented Interfaces:
TransactionCallback

public class WebSphereTransactionCallback


extends java.lang.Object


implements TransactionCallback

A TransactionCallback plugin used to automatically enlist the ObjectGrid transaction as a volatile participant in a WebSphere JTA transaction. The ObjectGrid transaction is then called to "commit" or "rollback" its changes immediately after the two-phase commit stage of the JTA transaction. However, if the ObjectGrid transaction fails to commit or rollback, the failure does not affect the JTA transaction.

The WebSphereTransactionCallback provides an implementation of the isExternalTransactionActive method to determine if a WebSphere Application Server transaction is active. If the method returns true, ObjectGrid automatically begins an ObjectGrid transaction and when the WebSphere transaction commits or rolls back, the ObjectGrid transaction will also be committed or rolled back.

This class may be extended to allow for application specific implementations to use the WebSphere transaction manager to control their ObjectGrid and other application resources together.

If this class is used outside of a WebSphere Application Server environment, the isExternalTransactionActive will return false.

Since:
WAS XD 6.1 FIX3, XC10

Nested Class Summary
 
Nested classes/interfaces inherited from interface com.ibm.websphere.objectgrid.plugins.TransactionCallback

TransactionCallback.BeforeCommit
 
Constructor Summary
WebSphereTransactionCallback()
          The default constructor.
 
Method Summary
void begin(TxID id)
          Invoked when starting a Session transaction.
void commit(TxID id)
          Invoked when committing a Session transaction.
void initialize(ObjectGrid objectGrid)
          Invoked when an ObjectGrid is initialized.
boolean isExternalTransactionActive(Session session)
          This method returns true if a WebSphere JTA transaction is active.
void rollback(TxID id)
          Invoked when rolling back a Session transaction.
 
Methods inherited from class java.lang.Object

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

Constructor Detail

WebSphereTransactionCallback

public WebSphereTransactionCallback()

The default constructor.

Method Detail

begin

public void begin(TxID id)

Description copied from interface: TransactionCallback
Invoked when starting a Session transaction.

A TransactionCallback can communicate the begin processing (along with the TxID) to the appropriate BackingMap and/or Loader. The Loader may use this signal to start a corresponding transaction on the underlying connection to a database.

Specified by:
begin in interface TransactionCallback

Parameters:
id - transaction identifer (TxID)

commit

public void commit(TxID id)

http://publib.boulder.ibm.com/infocenter/wdpxc/v2http://pic.dhe.ibm.com/infocenter/wxsinfo/v8r6/topic/com.ibm.websphere.extremescale.javadoc.doc/topics/com/ibm/websphere/objectgrid/plugins/TransactionCallback.html

Description copied from interface: TransactionCallback
Invoked when committing a Session transaction.

This method should be used to commit any underlying transaction and return any underlying connection back to the pool. The TxID is provided to determine which transaction is being committed

Specified by:
commit in interface TransactionCallback

initialize

public void initialize(ObjectGrid objectGrid)

Description copied from interface: TransactionCallback
Invoked when an ObjectGrid is initialized.

This method is called so this object can do any implementation specific intialization.

Specified by:
initialize in interface TransactionCallback

isExternalTransactionActive

public boolean isExternalTransactionActive(Session session)

This method returns true if a WebSphere JTA transaction is active. If a problem occurs in determining if a transaction is active, an ObjectGridRuntimeException will be thrown.

Specified by:
isExternalTransactionActive in interface TransactionCallback

Parameters:
session - the session which the application is using
Returns:
true if an auto begin should be done, false if this is not the case
Throws:

rollback

public void rollback(TxID id)

Description copied from interface: TransactionCallback
Invoked when rolling back a Session transaction.

This method should be used to roll back any underlying transaction and return any underlying connection back to the pool. The TxID is provided to determine which transaction is being committed

Specified by:
rollback in interface TransactionCallback


com.ibm.websphere.objectgrid.plugins
Interface BeanFactory

public interface BeanFactory

Implement this interface to allow bean factories like Spring or Google guice to be integrated. This allows ObjectGrid to delegate to an external Bean Factory to instantiate beans needed by ObjectGrid.

Since:
WAS XD 6.1 FIX3, XC10

Method Summary
java.lang.Object getBean(java.lang.String name)
          This returns an instance of the bean with the specified name.
 

Method Detail

getBean

java.lang.Object getBean(java.lang.String name)

This returns an instance of the bean with the specified name.

Parameters:
name - The name of the bean instance to return.
Returns:
the bean instance.


com.ibm.websphere.objectgrid.plugins
Interface CacheEntry

All Superinterfaces:
java.io.Serializable

public interface CacheEntry
extends java.io.Serializable

This interface represents a cache entry in an ObjectGrid map.

Since:
WAS XD 6.0, XC10

Method Summary
java.lang.Object getCommittedValue()
          Returns the committed value for this entry.
java.lang.Object getKey()
          Returns the key for this entry.
java.util.Collection getKeywords()
          Returns the list of keywords associated with this entry.
long getLastAccessTime()
          Returns the last time this entry was accessed.
long getTTL()
          Returns the time-to-live value for this entry.
boolean isInBackingMap()
          Indicates whether this entry is in the BackingMap
 

Method Detail

isInBackingMap

boolean isInBackingMap()

Indicates whether this entry is in the BackingMap

Returns:
Returns true if this element is in the BackingMap

getKey

java.lang.Object getKey()

Returns the key for this entry.

For a CacheEntry on an ObjectMap configured to use a KeySerializerPlugin, the value will be a SerializedKey object. If required, you can use the SerializedEntry.getObject() method to retrieve (possibly inflating the serialized object) the original key object.

Returns:
the key

getCommittedValue

java.lang.Object getCommittedValue()

Returns the committed value for this entry.

The type of the object returned from the getCommittedValue() method depends on various configuration and storage options used by the ObjectMap that holds the CacheEntry. In the default case, getCommittedValue() returns the Java object of the same type that was put into the map. For an ObjectMap configured to use a ValueSerializerPlugin, the committed value depends on the underlying storage mechanism, typically represented as an array of bytes.

Returns:
the committed value

getTTL

long getTTL()

Returns the time-to-live value for this entry.

Returns:
the time-to-live value

getLastAccessTime

long getLastAccessTime()

Returns the last time this entry was accessed.

Returns:
last access time.

getKeywords

java.util.Collection getKeywords()

Returns the list of keywords associated with this entry.

Returns:
a list of keywords


com.ibm.websphere.objectgrid.plugins
Class CacheEntryException

java.lang.Object
  ava.lang.Throwable
      ava.lang.Exception
          com.ibm.websphere.objectgrid.ObjectGridException
              com.ibm.websphere.objectgrid.plugins.CacheEntryException

All Implemented Interfaces:
IObjectGridException, java.io.Serializable

public class CacheEntryException
extends ObjectGridException

This exception indicates an error occurred during a cache entry operation.

Since:
WAS XD 6.0, XC10

Constructor Summary
CacheEntryException()
          Constructs a new CacheEntryException with null as its detail message.
CacheEntryException(java.lang.String message)
          Constructs a new CacheEntryException with the specified detail message.
CacheEntryException(java.lang.String message, java.lang.Throwable cause)
          Constructs a new CacheEntryException with the specified detail message and cause.
CacheEntryException(java.lang.Throwable cause)
          Constructs a new CacheEntryException with a specified cause.
 
Method Summary
 
Methods inherited from class com.ibm.websphere.objectgrid.ObjectGridException

getCause, initCause
 
Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
 
Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

CacheEntryException

public CacheEntryException()

Constructs a new CacheEntryException with null as its detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

CacheEntryException

public CacheEntryException(java.lang.String message)

Constructs a new CacheEntryException with the specified detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

Parameters:
message - the detail message. The detail message is saved for later Throwable.getMessage()

CacheEntryException

public CacheEntryException(java.lang.String message,
                           java.lang.Throwable cause)

Constructs a new CacheEntryException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this CacheEntryException's detail message.

Parameters:
message - the detail message (which is saved for later retrieval by the getMessage method).
cause - the cause (which is saved for later retrieval by the getCause method). (Anull value is permitted, and indicates that the cause is nonexistent or Throwable.getMessage()

CacheEntryException

public CacheEntryException(java.lang.Throwable cause)

Constructs a new CacheEntryException with a specified cause. The cause and a detail message of (cause==null ? null : cause.toString()) is used (which typically contains the class and detail message of cause). This constructor is useful for CacheEntryExceptions that are little more than wrappers for other throwables.

Parameters:
cause - is the exception that caused this exception to be thrown, which is saved for later retrieval by the getCause() method. A null value is permitted and indicates that the cause


com.ibm.websphere.objectgrid.plugins
Interface EvictionEventCallback

public interface EvictionEventCallback

An instance of EvictionEventCallback is passed into the Evictor at initialization time. When an eviction method is called, corresponding methods of EvictionEventCallback will be called so the BackingMap can process evictions.

Since:
WAS XD 6.0, XC10
EvictorData

Method Summary
void evictEntries(java.util.List keysToEvictList)
          If an Evictor chooses not to implement the EvictorData interface, this method can be used to evict a map entry.
void evictMapEntries(java.util.List evictorDataList)
          This method is the preferred method for the Evictor to use when evicting map entries.
EvictorData getEvictorData(java.lang.Object key)
          Gets the evictor data for a specified BackingMap cache entry.
void setEvictorData(java.lang.Object key, EvictorData data)
          Sets the evictor data for a specified BackingMap cache key.
 

Method Detail

setEvictorData

void setEvictorData(java.lang.Object key,
                    EvictorData data)

Sets the evictor data for a specified BackingMap cache key.

This method can be used by an implementor of the Evictor interface to keep data that the evictor needs for determining which cache entry to evict.

Parameters:
key - is the key for accessing a BackingMap entry.
data - the EvictorData object to store as evictor data for a specified key.
Throws:
java.lang.IllegalArgumentException - if key is a null reference or there is no BackingMap cache entry for this key.
Since:
WAS XD 6.0.1

getEvictorData

EvictorData getEvictorData(java.lang.Object key)

Gets the evictor data for a specified BackingMap cache entry.

Parameters:
key - the key for the BackingMap entry to set.
Returns:
if the specified key is not found in BackingMap, then the special value EvictorData.KEY_NOT_FOUND is returned. If the key is found in the BackingMap, the same reference that was previously passed to the setEvictorData(Object, EvictorData) method of this interface is returned. A null reference is returned if the key is found, but the setEvictorData method was not previously called for the specified key.
Throws:
java.lang.IllegalArgumentException - if key is a null reference.
Since:
WAS XD 6.0.1
EvictorData.KEY_NOT_FOUND

evictMapEntries

void evictMapEntries(java.util.List evictorDataList)
                     throws ObjectGridException

This method is the preferred method for the Evictor to use when evicting map entries. A list of EvictorData objects is passed as an argument to this method. For each EvictorData object in the list, the key is obtained from the EvictorData object and used to determine which BackingMap entry to evict. The BackingMap entry is evicted if and only if the cache entry for BackingMap entry contains the exact same EvictorData object in it. That is, the java == operator is used to ensure it is the exact same EvictorData object. If the == operator indicates a different object, then the map entry is not evicted. For those map entries that are physically evicted from the map, the Evictor will receive notification through its apply method.

Parameters:
evictorDataList - a list of EvictorData objects to process. The caller must guarantee this parameter is not null or contain any null references.
Throws:
ObjectGridException - if an error occurs during processing
java.lang.ClassCastException - if an object in evictorDataList does not implement the EvictorData interface.
Since:
WAS XD 6.0.1
EvictorData.getKey()

evictEntries

void evictEntries(java.util.List keysToEvictList)
                  throws ObjectGridException

If an Evictor chooses not to implement the EvictorData interface, this method can be used to evict a map entry. However, the Evictor must be prepared to handle the exposure of an application removing and recreating a map entry before the Evictor has an opportunity to call this method.

For this method, a list of map keys is passed. The list is evaluated and an eviction is conducted on the list. When the entries are physically evicted from the map, the Evictor will receive notification through its apply method.

Parameters:
keysToEvictList - List of keys to evict from the map. The caller must guarantee this parameter is not null or contain any null references.
Throws:


com.ibm.websphere.objectgrid.plugins
Interface Evictor

All Known Implementing Classes:
LFUEvictor, LRUEvictor

public interface Evictor

Data contained in a BackingMap are evicted when the map is full. This plugin is used by the BackingMap to determine when and what to evict from the map based on some algorithm (LRU, LFU, time based, etc).

An Evictor implementation that also implements the BackingMapLifecycleListener interface will be automatically added as an EventListener on the BackingMap when the evictor set on the backing map.

An Evictor may also implement the BackingMapPlugin interface in order to receive enhanced BackingMap plug-in lifecycle method calls. The plug-in is then also required to correctly implement each of the bean methods related to introspection of its state (for example isInitialized(), isDestroyed(), etc).

Since:
WAS XD 6.0, XC10
BackingMap.setEvictor(Evictor), EvictorData

Method Summary
void activate()
          This method is called to activate the Evictor.
void apply(LogSequence sequence)
          Called after a transaction has committed to allow the evictor to track object usage in the BackingMap.
void deactivate()
          This method is called to deactivate the Evictor.
void destroy()
          Called when the BackingMap associated with this evictor is destroyed.
void initialize(BackingMap map, EvictionEventCallback callback)
          Called by a BackingMap instance during the evictor initialization time.
 

Method Detail

initialize

void initialize(BackingMap map,
                EvictionEventCallback callback)

Called by a BackingMap instance during the evictor initialization time.

The BackingMap calls this method so the Evictor instance can have references to the BackingMap and EvictionEventCallback instances. The evictor can signal events to have specific entries evicted using the EvictionEventCallback.

EvictionEventCallback

destroy

void destroy()

Called when the BackingMap associated with this evictor is destroyed.

This method is the opposite of the initialize method. When it is called, the Evictor can free up any resources it uses.

apply

void apply(LogSequence sequence)

Called after a transaction has committed to allow the evictor to track object usage in the BackingMap.

This method also reports any entries that have been successfully evicted. Note, this method is not called for transactions that are rolled back. If there is a need to track object usage for rolled back transactions, the evictor must implement the RollbackEvictor interface as well.

This method is called after a transaction has completed. Consequently, all transaction locks that were acquired by the completed transaction are no longer held. Potentially, multiple threads could call this method concurrently and each thread would be completing its own transaction. Since transaction locks are already released by the completed transaction, this method must provide its own synchronization to ensure it is thread safe. For an Evictor in an ObjectMap configured to use a KeySerializerPlugin or ValueSerializerPlugin, the keys and values objects in the LogSequence will be SerializedKey or SerializedValue objects respectively. If required, you can use the SerializedEntry.getObject() method to retrieve (possibly inflating the serialized object) the original key or value object.

activate

void activate()

This method is called to activate the Evictor. Until this method is called, the Evictor must not use the EvictionEventCallback interface to evict any map entries. If it does use the EvictionEventcallback interface to evict map entries prior to activate being called, an IllegalStateException is thrown.

deactivate

void deactivate()

This method is called to deactivate the Evictor. Once this method is called, the Evictor must quit using the EvictionEventCallback interface to evict any map entries. If it does use the EvictionEventcallback interface after this method is called, an IllegalStateException is thrown.


com.ibm.websphere.objectgrid.plugins
Interface EvictorData

All Known Implementing Classes:
EvictorData.SpecialEvictorData

public interface EvictorData

This interface is optionally used by an implementator of the Evictor interface. Application changes applied to a BackingMap are asynchronous from the Evictor activity. The Evictor is not notified of changes to the BackingMap until after application transactions are committed. Consequently, if an Evictor decides to evict a map entry, it is possible that the BackingMap could evict an entry that was different from the original entry it was tracking. For example, consider that an application could execute a transaction that removes a map entry. Before the Evictor is notified of the remove, another transaction inserts a new entry into the BackingMap for the same key as the old entry. Consequently, the Evictor could evict the newly created entry when it meant to evict the old entry. To help close this small timing window, the Evictor can use this interface to associate evictor specific data with a map entry. The Evictor can then do the following:

  • store the EvictorData object for a map entry using the EvictionEventCallback.setEvictorData(Object, EvictorData) method.
  • retrieve the EvictorData object for a map entry by using the EvictionEventCallback.getEvictorData(Object) method.
  • Conditionally evict a map entry if and only if the cache entry for a specified key has the exact same EvictorData object (the java == operator returns true) associated with it using the EvictionEventCallback.evictMapEntries(List) method.

Since:
WAS XD 6.0.1, XC10
EvictionEventCallback

Nested Class Summary
static class EvictorData.SpecialEvictorData
          Special value class used for representing the key not being found in the BackingMap.
 
Field Summary
static EvictorData KEY_NOT_FOUND
          A special value indicating that the key was not found.
 
Method Summary
java.lang.Object getKey()
          Retrieves the key object for this EvictorData instance.
 

Field Detail

KEY_NOT_FOUND

static final EvictorData KEY_NOT_FOUND

A special value indicating that the key was not found.

Method Detail

getKey

java.lang.Object getKey()

Retrieves the key object for this EvictorData instance.

Returns:
the same key object that was passed to the EvictionEventCallback.setEvictorData(Object, EvictorData) method when this EvictorData was associated with the map entry


com.ibm.websphere.objectgrid.plugins
Class EvictorData.SpecialEvictorData

java.lang.Object
  com.ibm.websphere.objectgrid.plugins.EvictorData.SpecialEvictorData

All Implemented Interfaces:
EvictorData

Enclosing interface:
EvictorData

public static final class EvictorData.SpecialEvictorData
extends java.lang.Object
implements EvictorData

Special value class used for representing the key not being found in the BackingMap.

Since:
WAS XD 6.0.1

Nested Class Summary
 
Nested classes/interfaces inherited from interface com.ibm.websphere.objectgrid.plugins.EvictorData

EvictorData.SpecialEvictorData
 
Field Summary
 
Fields inherited from interface com.ibm.websphere.objectgrid.plugins.EvictorData

KEY_NOT_FOUND
 
Constructor Summary
EvictorData.SpecialEvictorData()
           
 
Method Summary
java.lang.Object getKey()
          Dummy implementation method since this class will not be called.
 
Methods inherited from class java.lang.Object

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

Constructor Detail

EvictorData.SpecialEvictorData

public EvictorData.SpecialEvictorData()

Method Detail

getKey

public java.lang.Object getKey()

Dummy implementation method since this class will not be called.

Specified by:
getKey in interface EvictorData


com.ibm.websphere.objectgrid.plugins
Class LoaderException

java.lang.Object
  ava.lang.Throwable
      ava.lang.Exception
          com.ibm.websphere.objectgrid.ObjectGridException
              com.ibm.websphere.objectgrid.plugins.LoaderException

All Implemented Interfaces:
IObjectGridException, java.io.Serializable

Direct Known Subclasses:
UnavailableServiceException

public class LoaderException
extends ObjectGridException

This exception is the base exception for any exceptions encountered by a Loader.

Since:
WAS XD 6.0, XC10
Serialized Form

Constructor Summary
LoaderException()
          Constructs a new LoaderException with null as its detail message.
LoaderException(java.lang.String message)
          Constructs a new LoaderException with the specified detail message.
LoaderException(java.lang.String message, java.lang.Throwable cause)
          Constructs a new LoaderException with the specified detail message and cause.
LoaderException(java.lang.Throwable cause)
          Constructs a new LoaderException with a specified cause.
 
Method Summary
 
Methods inherited from class com.ibm.websphere.objectgrid.ObjectGridException

getCause, initCause
 
Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
 
Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

LoaderException

public LoaderException()

Constructs a new LoaderException with null as its detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

LoaderException

public LoaderException(java.lang.String message)

Constructs a new LoaderException with the specified detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

Parameters:
message - the detail message. The detail message is saved for later Throwable.getMessage()

LoaderException

public LoaderException(java.lang.String message,
                       java.lang.Throwable cause)

Constructs a new LoaderException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this LoaderException's detail message.

Parameters:
message - the detail message (which is saved for later retrieval by the getMessage method).
cause - the cause (which is saved for later retrieval by the getCause method). (Anull value is permitted, and indicates that the cause is nonexistent or Throwable.getMessage()

LoaderException

public LoaderException(java.lang.Throwable cause)

Constructs a new LoaderException with a specified cause. The cause and a detail message of (cause==null ? null : cause.toString()) is used (which typically contains the class and detail message of cause). This constructor is useful for LoaderExceptions that are little more than wrappers for other throwables.

Parameters:
cause - is the exception that caused this exception to be thrown, which is saved for later retrieval by the getCause() method. A null value is permitted and indicates that the cause


com.ibm.websphere.objectgrid.plugins
Interface LogElement

All Superinterfaces:
java.io.Serializable

public interface LogElement
extends java.io.Serializable

LogElements are the individual entries within a LogSequence. A LogElement has attributes such as operation type (delete, insert, update, etc.), current value, last access time, versioned value, etc. A LogElement is created during a transaction to record in-flight operations. For a LogElement on an ObjectMap configured to use a KeySerializerPlugin or ValueSerializerPlugin, the keys and values objects in the LogElement will be SerializedKey or SerializedValue objects respectively. If required, you can use the SerializedEntry.getObject() method to retrieve (possibly inflating the serialized object) the original key or value object.

Since:
WAS XD 6.0, XC10

Nested Class Summary
static class LogElement.Type
          The Type class is used to represent a LogElement type.
 
Field Summary
static LogElement.Type CLEAR
          The Type that represents the CLEAR operation.
static int CODE_CLEAR
          The type code constant for CLEAR.
static int CODE_DELETE
          The type code constant for DELETE.
static int CODE_EVICT
          The type code constant for EVICT.
static int CODE_FETCH
          The type code constant for FETCH.
static int CODE_INSERT
          The type code constant for INSERT.
static int CODE_TOUCH
          The type code constant for TOUCH.
static int CODE_UNDO_BEFORE_IMAGE_KEYWORDS
          The code constant for UNDO_BEFORE_IMAGE_KEYWORDS.
static int CODE_UNDO_NOT_NEEDED
          The code constant for UNDO_NOT_NEEDED.
static int CODE_UPDATE
          The type code constant for UPDATE.
static LogElement.Type DELETE
          The Type that represents the DELETE operation.
static LogElement.Type EVICT
          The Type that represents the EVICT operation.
static LogElement.Type FETCH
          The Type that represents the FETCH operation.
static LogElement.Type INSERT
          The Type that represents the INSERT operation.
static LogElement.Type TOUCH
          The Type that represents the TOUCH operation.
static LogElement.Type UNDO_BEFORE_IMAGE_KEYWORDS
          The Type that represents the UNDO action to remove new keyword associations that were introduced in this LogElement.
static LogElement.Type UNDO_NOT_NEEDED
          The Type that represents an UNDO action is NOT required for this LogElement.
static LogElement.Type UPDATE
          The Type that represents the UPDATE operation.
 
Method Summary
java.lang.Object getAfterImage()
          Gets the "after image" value object.
java.lang.Object getBeforeImage()
          Gets the "before image" of the value object.
CacheEntry getCacheEntry()
          Returns the CacheEntry for this key.
java.lang.Object getCurrentValue()
          Gets the value for this LogElement.
java.lang.Object getKey()
          Returns the key for this LogElement.
long getLastAccessTime()
          Returns the last access time associated with this LogElement.
java.util.Collection getNewKeywords()
          Returns any new keywords that have been associated with this entry as a result of this transaction.
LogElement.Type getType()
          Gets the type of this LogElement.
LogElement.Type getUndoType()
          Returns what operation must be performed to "undo" a prior change the transaction made to the map entry.
java.lang.Object getVersionedValue()
          Gets the versioned object at the time the object was first associated with the transaction.
boolean isCascaded()
          Answers true if this LogElement is a result of a cascade operation.
boolean isPending()
          Answers true if this change has NOT been applied to the loader.
void setVersionedValue(java.lang.Object v)
          Used to update the versioned object after an update of map entry occurs.
 

Field Detail

CODE_INSERT

static final int CODE_INSERT

The type code constant for INSERT.

LogElement.Type.getCode(), Constant Field Values

CODE_UPDATE

static final int CODE_UPDATE

The type code constant for UPDATE.

LogElement.Type.getCode(), Constant Field Values

CODE_DELETE

static final int CODE_DELETE

The type code constant for DELETE.

LogElement.Type.getCode(), Constant Field Values

CODE_EVICT

static final int CODE_EVICT

The type code constant for EVICT.

LogElement.Type.getCode(), Constant Field Values

CODE_FETCH

static final int CODE_FETCH

The type code constant for FETCH.

LogElement.Type.getCode(), Constant Field Values

CODE_TOUCH

static final int CODE_TOUCH

The type code constant for TOUCH.

LogElement.Type.getCode(), Constant Field Values

CODE_UNDO_BEFORE_IMAGE_KEYWORDS

static final int CODE_UNDO_BEFORE_IMAGE_KEYWORDS

The code constant for UNDO_BEFORE_IMAGE_KEYWORDS. Used when a rollback does not need to undo any applied BackingMap changes, but it needs to invoke the keyword manager to remove any new keyword associates for the map entry introduced in this LogElement.

UNDO_BEFORE_IMAGE_KEYWORDS, Constant Field Values

CODE_CLEAR

static final int CODE_CLEAR

The type code constant for CLEAR.

Since:
WAS XD 6.1.0.3
LogElement.Type.getCode(), Constant Field Values

CODE_UNDO_NOT_NEEDED

static final int CODE_UNDO_NOT_NEEDED

The code constant for UNDO_NOT_NEEDED. Used to indicate no operation is needed to undo the changes for this LogElement since this LogElement was never processed.

Constant Field Values

INSERT

static final LogElement.Type INSERT

The Type that represents the INSERT operation.

UPDATE

static final LogElement.Type UPDATE

The Type that represents the UPDATE operation.

DELETE

static final LogElement.Type DELETE

The Type that represents the DELETE operation.

EVICT

static final LogElement.Type EVICT

The Type that represents the EVICT operation.

FETCH

static final LogElement.Type FETCH

The Type that represents the FETCH operation.

TOUCH

static final LogElement.Type TOUCH

The Type that represents the TOUCH operation.

CLEAR

static final LogElement.Type CLEAR

The Type that represents the CLEAR operation.

Since:
WAS XD 6.1.0.3

UNDO_BEFORE_IMAGE_KEYWORDS

static final LogElement.Type UNDO_BEFORE_IMAGE_KEYWORDS

The Type that represents the UNDO action to remove new keyword associations that were introduced in this LogElement.

UNDO_NOT_NEEDED

static final LogElement.Type UNDO_NOT_NEEDED

The Type that represents an UNDO action is NOT required for this LogElement.

Method Detail

getType

LogElement.Type getType()

Gets the type of this LogElement. The type indicates what operation needs to be applied to the map entry.

Returns:
the type of this LogElement.

getCurrentValue

java.lang.Object getCurrentValue()

Gets the value for this LogElement.

For a LogElement on an ObjectMap configured to use a ValueSerializerPlugin, the values in the LogSequence will be SerializedValue objects. If required, you can use the SerializedEntry.getObject() method to retrieve (possibly inflating the serialized object) the original value object.

The original value represents the new value that should be applied to the BackingMap and Loader. This value can be cast to ValueProxyInfo when a value interface is in use in order to determine the set of dirty attributes.

Returns:
the value in case of INSERT, UPDATE, or FETCH, null

getCacheEntry

CacheEntry getCacheEntry()

Returns the CacheEntry for this key. The key, current committed value, etc. can be accessed from the CacheEntry.

getKey()

isPending

boolean isPending()

Answers true if this change has NOT been applied to the loader.

Changes can previously be applied to a loader using the ObjectMap.flush() or Session.flush() methods. This method reveals whether the change in this LogElement has already been applied to the Loader using one of those methods.

Session.flush()

getVersionedValue

java.lang.Object getVersionedValue()

Gets the versioned object at the time the object was first associated with the transaction.

For a LogElement on an ObjectMap configured to use a or ValueSerializerPlugin, the versioned object will be returned as an XsDataInputStream, read will be SerializedKey or SerializedValue objects respectively. If required, you can use the SerializedEntry.getObject() method to retrieve (possibly inflating the serialized object) the original key or value object. For a LogElement on an ObjectMap configured to use a ValueSerializerPlugin that generates version objects, the version object will be the data stream representing the data.

setVersionedValue

void setVersionedValue(java.lang.Object v)

Used to update the versioned object after an update of map entry occurs.

The Loader can use this method when it is using an optimistic strategy and uses the OptimisticCallback.updateVersionedObjectForValue(Object) method to get an updated version object.

getNewKeywords

java.util.Collection getNewKeywords()

Returns any new keywords that have been associated with this entry as a result of this transaction.

Returns:
the list of new keywords.

getLastAccessTime

long getLastAccessTime()

Returns the last access time associated with this LogElement.

Returns:
last access time

getUndoType

LogElement.Type getUndoType()

Returns what operation must be performed to "undo" a prior change the transaction made to the map entry.

Note, an undo type of UNDO_NOT_NEEDED is returned if nothing needs to be undone for this LogElement.

Returns:
the "undo" type of this LogElement. It can be one of: INSERT, UPDATE, DELETE, UNDO_NOT_NEEDED, or UNDO_BEFORE_IMAGE_KEYWORDS

getBeforeImage

java.lang.Object getBeforeImage()

Gets the "before image" of the value object.

The "before image" is the value object that existed in map entry prior to applying a change to map entry. Note, it is possible for a null reference to be returned (e.g. in the case where a new map entry is created).

For a LogElement on an ObjectMap configured to use a ValueSerializerPlugin, the value will be a SerializedValue object. If required, you can use the SerializedEntry.getObject() method to retrieve (possibly inflating the serialized object) the original value object.

Returns:
the value prior to applying the change

getAfterImage

java.lang.Object getAfterImage()

Gets the "after image" value object.

The "after image" is the value object that existed in map entry after applying a change to the map entry. Note, it is possible for a null reference to be returned (e.g. in the case where an existing map entry is removed/evicted).

For a LogElement on an ObjectMap configured to use a ValueSerializerPlugin, the value will be a SerializedValue object. If required, you can use the SerializedEntry.getObject() method to retrieve (possibly inflating the serialized object) the original value object.

Returns:
the value after applying the change

isCascaded

boolean isCascaded()

Answers true if this LogElement is a result of a cascade operation. This only applies to ObjectGrid EntityManager programming model.

ObjectGrid EntityManager supports cascade operations. For example, when persisting an entity P, if P has a relation to entity C with CascadeType.PERSIST enabled, C will also be persisted as a result of the cascade operation. The method isCascaded() returns true for the LogElement object which represents C, and the method returns false for the LogElement object which represents P.

Returns:
true if the LogElement object is a result of cascade operation.
Since:
6.1.0.5 FIX1

getKey

java.lang.Object getKey()

Returns the key for this LogElement.

For a LogElement on an ObjectMap configured to use a KeySerializerPlugin, the value will be a SerializedKey object. If required, you can use the SerializedEntry.getObject() method to retrieve (possibly inflating the serialized object) the original key object.

This method can be used instead of LogElement.getCacheEntry().getKey().

Returns:
the key for this LogElement.
Since:
7.0


com.ibm.websphere.objectgrid.plugins
Class LogElement.Type

java.lang.Object
  com.ibm.websphere.objectgrid.plugins.LogElement.Type

All Implemented Interfaces:
java.lang.Comparable

Enclosing interface:
LogElement

public static class LogElement.Type
extends java.lang.Object
implements java.lang.Comparable

The Type class is used to represent a LogElement type.

Since:
WAS XD 6.0

Method Summary
int compareTo(java.lang.Object object)
           
int getCode()
          Gets the type code for this object.
java.lang.String toString()
           
 
Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

getCode

public int getCode()

Gets the type code for this object.

Returns:
the type code

compareTo

public int compareTo(java.lang.Object object)

Specified by:
compareTo in interface java.lang.Comparable

toString

public java.lang.String toString()

Overrides:
toString in class java.lang.Object


com.ibm.websphere.objectgrid.plugins
Interface LogSequence

All Superinterfaces:
java.io.Serializable

public interface LogSequence
extends java.io.Serializable

LogSequence is the ordered list of changes performed against a given map for a given transaction. These changes are recorded as LogElement objects.

Since:
WAS XD 6.0, XC10

Method Summary
java.util.Iterator getAllChanges()
          Returns an iterator for processing all of the changes for a LogSequence.
java.util.Iterator getChangesByKeys(java.util.Collection keys)
          Returns an iterator for processing the LogElements that have the requested keys.
java.util.Iterator getChangesByTypes(java.util.Collection types)
          Returns an iterator for processing the LogElements that are of the requested type.
java.lang.String getMapName()
          Returns the name of the map that these changes apply to.
java.lang.String getObjectGridName()
          Returns the name of the ObjectGrid that houses the map that these changes apply to.
java.util.Iterator getPendingChanges()
          Returns an iterator for processing all of the "pending" changes for a LogSequence (for example, pending inserts, updates, and deletes).
boolean isDirty()
          Returns whether this LogSequence has any LogElements that would "dirty" a Map.
boolean isRollback()
          Returns whether or not this LogSequence was generated to rollback a transaction.
int size()
          Returns the total number of LogElements within this LogSequence.
 

Method Detail

size

int size()

Returns the total number of LogElements within this LogSequence.

Returns:
total number of LogElements

getPendingChanges

java.util.Iterator getPendingChanges()

Returns an iterator for processing all of the "pending" changes for a LogSequence (for example, pending inserts, updates, and deletes).

This method is normally used by a Loader. A pending change is one that has not been written out to a loader yet using a flush() operation. Note, the returned iterator's remove() is not allowed to be called and will throw an exception.

Session.flush()

getAllChanges

java.util.Iterator getAllChanges()

Returns an iterator for processing all of the changes for a LogSequence.

This method would normally be used by an Evictor and other plugins that want to know all of the changes introduced by this LogSequence. Note, the returned iterator's remove() is not allowed to be called and will throw an exception.

Returns:
an Iterator for processing all of the LogElement changes

getChangesByTypes

java.util.Iterator getChangesByTypes(java.util.Collection types)

Returns an iterator for processing the LogElements that are of the requested type.

Each member of the input Collection should be one of the defined LogElement Types (INSERT, UPDATE, DELETE, FETCH, TOUCH, or EVICT). Note, the returned iterator's remove() is not allowed to be called and will throw an exception.

Parameters:
types - A Collection of LogElement Types (INSERT, UPDATE, etc)
Returns:
Iterator for processing all LogElements that support the input Type(s)
Throws: LogElement.EVICT, LogElement.FETCH, LogElement.INSERT, LogElement.TOUCH, LogElement.UPDATE, LogElement.CLEAR

getChangesByKeys

java.util.Iterator getChangesByKeys(java.util.Collection keys)

Returns an iterator for processing the LogElements that have the requested keys.

Note, the returned iterator's remove() is not allowed to be called and will throw an exception.

Parameters:
keys - a collection of key objects
Returns:
an Iterator for processing all LogElements that match the input key(s)

getMapName

java.lang.String getMapName()

Returns the name of the map that these changes apply to.

The caller can use the return value of this method as input to the Session.getMap(String) method.

getObjectGridName

java.lang.String getObjectGridName()

Returns the name of the ObjectGrid that houses the map that these changes apply to.

Returns:
The name of the ObjectGrid that this LogSequence is associated with
Since:
WAS XD 6.0.1

isDirty

boolean isDirty()

Returns whether this LogSequence has any LogElements that would "dirty" a Map.

That is, if it contains any LogElements of any type other than Fetch/Get, it is considered "dirty".

Returns:
true if the LogSequence would modify a Map, if applied; false if the LogSequence would not modify a Map, if applied

isRollback

boolean isRollback()

Returns whether or not this LogSequence was generated to rollback a transaction.

Note, depending on when this LogSequence is used, the transaction itself might already be rolled back.

Returns:
true iff this LogSequence was generated to rollback a transaction.
Since:
WAS XD 6.0.1


com.ibm.websphere.objectgrid.plugins
Interface LogSequenceFilter

public interface LogSequenceFilter

This interface can be used to filter a LogSequence. As an operation, such as serialization, needs to know whether a given LogElement should be included or not, this callback object will be used for the boolean check. If the given LogElement should be used in the operation, then "true" should be returned. If the given LogElement should not be used, then "false" should be returned. This interface is primarily used by the serialize method of the LogSequenceTransformer class.

Since:
WAS XD 6.0, XC10

Method Summary
boolean accept(LogElement logElement)
          Returns true if the given LogElement should be used; false if the given LogElement should not be used.
 

Method Detail

accept

boolean accept(LogElement logElement)

Returns true if the given LogElement should be used; false if the given LogElement should not be used.

Parameters:
logElement - the LogElement to be filtered
Returns:
true if the given LogElement should be used in the operation; false otherwise.


com.ibm.websphere.objectgrid.plugins
Interface MapEventListener

All Superinterfaces:
EventListener

public interface MapEventListener
extends EventListener

This callback interface is implemented by the application when it wants to receive events about a Map such as the eviction of a map entry.

Since:
WAS XD 6.0, XC10
BackingMap.removeMapEventListener(EventListener), EventListener

Method Summary
void entryEvicted(java.lang.Object key, java.lang.Object value)
          Invoked when the specified entry is evicted from the map.
void preloadCompleted(java.lang.Throwable t)
          Invoked when the preloading of this map has completed.
 

Method Detail

entryEvicted

void entryEvicted(java.lang.Object key,
                  java.lang.Object value)

Invoked when the specified entry is evicted from the map.

The eviction could have occurred either by an Evictor's processing or by invoking one of the invalidate methods on the ObjectMap.

For a MapEventListener in an ObjectMap configured to use a KeySerializerPlugin or ValueSerializerPlugin, the keys and values objects passed will be SerializedKey or SerializedValue objects respectively. If required, you can use the SerializedEntry.getObject() method to retrieve (possibly inflating the serialized object) the original key or value object.

Parameters:
key - The key for the map entry that was evicted.
value - The value that was in in the map entry evicted. The value object EvictionEventCallback, ObjectMap.invalidate(Object, boolean)

preloadCompleted

void preloadCompleted(java.lang.Throwable t)

Invoked when the preloading of this map has completed.

This method is useful to determine when a preload operation finishes if asynchronous preloading is enabled. In addition if any error occurred during synchronous or asynchronous preload, it is reported with the invocation of this method.

Parameters:
t - A Throwable object that indicates if preload completed without any Throwable occuring during the preload of the map. A null reference indicates preload completed without any Throwable objects occuring BackingMap.setPreloadMode(boolean)


com.ibm.websphere.objectgrid.plugins
Interface ObjectGridEventGroup

public interface ObjectGridEventGroup

This is a set of single method interfaces for fine grained events delivered for an ObjectGrid. Classes implementing these interfaces AND ObjectGridEventListener can receive these events. If an ObjectGridEventListener implements ANY of these interfaces that only the specific methods on the interfaces implemented will be called.

Since:
WAS XD 6.1, XC10

Nested Class Summary
static interface ObjectGridEventGroup.ShardEvents
          These events are fired when a shard is made a primary shard and when the shard is demoted from a primary.
static interface ObjectGridEventGroup.ShardLifecycle
          These events are fired when an ObjectGrid shard is initialized and destroyed.
static interface ObjectGridEventGroup.TransactionEvents
          These events are called every single transaction.
 


com.ibm.websphere.objectgrid.plugins
Interface ObjectGridEventGroup.ShardLifecycle

Enclosing interface:
ObjectGridEventGroup

public static interface ObjectGridEventGroup.ShardLifecycle

These events are fired when an ObjectGrid shard is initialized and destroyed. A shard can be activated/deactivated multiple times within these two events.

Method Summary
void destroy()
          Called when the ObjectGrid associated with this listener is destroyed.
void initialize(Session session)
          Invoked when an ObjectGrid is initialized.
 

Method Detail

initialize

void initialize(Session session)

Invoked when an ObjectGrid is initialized.

A usable Session instance is passed to this listener to provide all of the necessary access to the various ObjectGrid objects.

destroy

void destroy()

Called when the ObjectGrid associated with this listener is destroyed.

This method is the opposite of the initialize method. When it is called, the listener can free up any resources it uses.


com.ibm.websphere.objectgrid.plugins
Interface ObjectGridEventGroup.ShardEvents

Enclosing interface:
ObjectGridEventGroup

public static interface ObjectGridEventGroup.ShardEvents

These events are fired when a shard is made a primary shard and when the shard is demoted from a primary.

Method Summary
void shardActivated(ObjectGrid grid)
          This is called when a shard is promoted to a primary.
void shardDeactivate(ObjectGrid grid)
          This is called when a primary shard is demoted to a replica.
 

Method Detail

shardActivated

void shardActivated(ObjectGrid grid)

This is called when a shard is promoted to a primary.

Parameters:
grid - This is a local reference to the shard containing the primary data.

shardDeactivate

void shardDeactivate(ObjectGrid grid)

This is called when a primary shard is demoted to a replica. This can happen is the balancer decides the primary is better placed in a different container. Replication is still active until this method returns to the caller. If any application controlled transactions are in flight then they should be stopped before returning. Once this method returns then any remaining transactions will fail.

Parameters:
grid - A reference to the shard.


com.ibm.websphere.objectgrid.plugins
Interface ObjectGridEventGroup.TransactionEvents

Enclosing interface:
ObjectGridEventGroup

public static interface ObjectGridEventGroup.TransactionEvents

These events are called every single transaction. These are primarily used when transaction level listening is required. This is usually for pushing changes or invalidation events to peer caches for simple scenarios.

Method Summary
void transactionBegin(java.lang.String txid, boolean isWriteThroughEnabled)
          Signals the beginning of a Session transaction.
void transactionEnd(java.lang.String txid, boolean isWriteThroughEnabled, boolean committed, java.util.Collection changes)
          Signals the ending of a Session transaction.
 

Method Detail

transactionBegin

void transactionBegin(java.lang.String txid,
                      boolean isWriteThroughEnabled)

Signals the beginning of a Session transaction.

A stringified version of the TxID is provided for correlating with the end of the transaction, if so desired. The type of transaction is also provided by the isWriteThroughEnabled boolean parameter.

Parameters:
txid - Stringified version of the TxID
isWriteThroughEnabled - boolean flag indicating whether the Session transaction was started using the Session.beginNoWriteThrough(). method. false is passed if Session.beginNoWriteThrough()

transactionEnd

void transactionEnd(java.lang.String txid,
                    boolean isWriteThroughEnabled,
                    boolean committed,
                    java.util.Collection changes)

Signals the ending of a Session transaction.

A string version of the TxID is provided for correlating with the begin of the transaction, if so desired. Map changes are also reported with the collection of LogSequences passed to this method. Typical uses of this event are for customers doing custom peer invalidation or peer commit push. This event listener gives them the changes. Calls to this method are made after commit and are sequenced so that they are delivered one by one, not in parallel. The event order is the commit and rollback order.

Parameters:
txid - string version of the TxID
isWriteThroughEnabled - boolean flag indicating whether the Session transaction was started using the Session.beginNoWriteThrough(). method. false is passed if beginNoWriteThrough() was used.
committed - a boolean flag indicating whether the transaction was committed (true) or rolled back (false)
changes - a Collection of LogSequences representing the changes Session.begin(), Session.beginNoWriteThrough(), Session.commit(), Session.rollback()


com.ibm.websphere.objectgrid.plugins
Interface ObjectGridEventListener

All Superinterfaces:
EventListener

public interface ObjectGridEventListener
extends EventListener

This interface is used to create an implementation of an event listener for an ObjectGrid. Instances of ObjectGridEventListeners are set on the ObjectGrid interface. Any significant events are communicated to the application using the methods outlined below. When using Java 5, this callback also supports new callback annotation mechanism.

Since:
WAS XD 6.0, XC10
ObjectGrid.removeEventListener(EventListener), EventListener

Method Summary
void destroy()
          Called when the ObjectGrid associated with this listener is destroyed.
void initialize(Session session)
          Invoked when an ObjectGrid is initialized.
void transactionBegin(java.lang.String txid, boolean isWriteThroughEnabled)
          Signals the beginning of a Session transaction.
void transactionEnd(java.lang.String txid, boolean isWriteThroughEnabled, boolean committed, java.util.Collection changes)
          Signals the ending of a Session transaction.
 

Method Detail

initialize

void initialize(Session session)

Invoked when an ObjectGrid is initialized.

A usable Session instance is passed to this listener to provide all of the necessary access to the various ObjectGrid objects.

transactionBegin

void transactionBegin(java.lang.String txid,
                      boolean isWriteThroughEnabled)

Signals the beginning of a Session transaction.

A stringified version of the TxID is provided for correlating with the end of the transaction, if so desired. The type of transaction is also provided by the isWriteThroughEnabled boolean parameter.

Parameters:
txid - Stringified version of the TxID
isWriteThroughEnabled - boolean flag indicating whether the Session transaction was started using the Session.beginNoWriteThrough(). method. false is passed if Session.beginNoWriteThrough()

transactionEnd

void transactionEnd(java.lang.String txid,
                    boolean isWriteThroughEnabled,
                    boolean committed,
                    java.util.Collection changes)

Signals the ending of a Session transaction.

A string version of the TxID is provided for correlating with the begin of the transaction, if so desired. Map changes are also reported with the collection of LogSequences passed to this method. Typical uses of this event are for customers doing custom peer invalidation or peer commit push. This event listener gives them the changes. Calls to this method are made after commit and are sequenced so that they are delivered one by one, not in parallel. The event order is the commit and rollback order.

For an ObjectGridEventListener receiving changes in an ObjectMap that is configured to use a KeySerializerPlugin or ValueSerializerPlugin, the keys and values objects in the LogSequences will be SerializedKey or SerializedValue objects respectively. If required, you can use the SerializedEntry.getObject() method to retrieve (possibly inflating the serialized object) the original key or value object.

Parameters:
txid - string version of the TxID
isWriteThroughEnabled - boolean flag indicating whether the Session transaction was started using the Session.beginNoWriteThrough(). method. false is passed if beginNoWriteThrough() was used.
committed - a boolean flag indicating whether the transaction was committed (true) or rolled back (false)
changes - a Collection of LogSequences representing the changes Session.begin(), Session.beginNoWriteThrough(), Session.commit(), Session.rollback()

destroy

void destroy()

Called when the ObjectGrid associated with this listener is destroyed.

This method is the opposite of the initialize method. When it is called, the listener can free up any resources it uses.


com.ibm.websphere.objectgrid.plugins
Interface ReplicationMapListener

public interface ReplicationMapListener

This interface is used to create an implementation of an event listener for client-side maps that are in replication mode. Registered listeners receive notification callbacks for replication start and exit events and data changes.

Listener instances can be registered with a map using the ClientReplicableMap.enableClientReplication(com.ibm.websphere.objectgrid.ClientReplicableMap.Mode, int[], ReplicationMapListener) method.

Since:
WAS XD 6.1, XC10

Method Summary
void onData(LogSequence logSequence)
          This method is invoked when a data change is replicated to the client replication map.
void replicationExits()
          This method is invoked when replication has been disabled for this map.
void replicationStarts()
          This method is invoked when a snapshot mode replica has been synchronized with the client or a continuous replica has started replicating.
 

Method Detail

replicationStarts

void replicationStarts()

This method is invoked when a snapshot mode replica has been synchronized with the client or a continuous replica has started replicating.

See also: ClientReplicableMap.enableClientReplication(com.ibm.websphere.objectgrid.ClientReplicableMap.Mode, int[], ReplicationMapListener)

onData

void onData(LogSequence logSequence)

This method is invoked when a data change is replicated to the client replication map.

Parameters:
logSequence - the log sequence containing all of the data changes.

replicationExits

void replicationExits()

This method is invoked when replication has been disabled for this map.


com.ibm.websphere.objectgrid.plugins
Interface TransactionCallback

All Known Subinterfaces:
TransactionCallback.BeforeCommit

All Known Implementing Classes:
WebSphereTransactionCallback

public interface TransactionCallback

Calling methods on a Session will send corresponding events to the TransactionCallback. An ObjectGrid can have zero or one TransactionCallback. BackingMaps defined on an ObjectGrid with a TransactionCallback should have corresponding Loaders.

A TransactionCallback works with Loaders and place transaction specific objects in slots on the TxID object that Loaders can obtain. Examples are database connections, prepared statement caches, etc. The TransactionCallback should reserve slots in the TxID by calling ObjectGrid.reserveSlot(String) using the name TxID.SLOT_NAME. The TransactionCallback can then put an object at that index in the TxID. A Loader can retrieve the index used by the TransactionCallback by calling an internal method on the TransactionCallback's implementation. A reference to the configured TransactionCallback can be found using the TxID.getSession().getObjectGrid().getTransactionCallback() code sequence.

A TransactionCallback implementation that also implements the ObjectGridLifecycleListener interface will be automatically added as an EventListener on the ObjectGrid when the callback is set on the object grid.

A TransactionCallback may implement the ObjectGridPlugin interface in order to receive enhanced ObjectGrid plug-in lifecycle method calls. The plug-in is also required to correctly implement each of the bean methods related to introspection of its state (for example isInitialized(), isDestroyed(), etc).

Since:
WAS XD 6.0, XC10
ObjectGrid.addEventListener(EventListener), ObjectGrid.getTransactionCallback(), ObjectGrid.reserveSlot(String), ObjectGrid.setTransactionCallback(TransactionCallback), Session.getObjectGrid(), TxID.putSlot(int, Object), TxID.getSlot(int), TxID.getSession()

Nested Class Summary
static interface TransactionCallback.BeforeCommit
          The BeforeCommit optional mix-in interface for the TransactionCallback plug-in interface allows plug-ins to be notified at the beginning of a Session.commit().
 
Method Summary
void begin(TxID id)
          Invoked when starting a Session transaction.
void commit(TxID id)
          Invoked when committing a Session transaction.
void initialize(ObjectGrid objectGrid)
          Invoked when an ObjectGrid is initialized.
boolean isExternalTransactionActive(Session session)
          Called when an application attempts to use a Session with no transaction active.
void rollback(TxID id)
          Invoked when rolling back a Session transaction.
 

Method Detail

initialize

void initialize(ObjectGrid objectGrid)
                throws TransactionCallbackException

Invoked when an ObjectGrid is initialized.

This method is called so this object can do any implementation specific intialization.

Parameters:
objectGrid - A reference to the ObjectGrid.
Throws:

begin

void begin(TxID id)
           throws TransactionCallbackException

Invoked when starting a Session transaction.

A TransactionCallback can communicate the begin processing (along with the TxID) to the appropriate BackingMap and/or Loader. The Loader may use this signal to start a corresponding transaction on the underlying connection to a database.

Parameters:
id - transaction identifer (TxID)
Throws: Session.beginNoWriteThrough(), TxID

commit

void commit(TxID id)
            throws TransactionCallbackException

Invoked when committing a Session transaction.

This method should be used to commit any underlying transaction and return any underlying connection back to the pool. The TxID is provided to determine which transaction is being committed

Parameters:
id - transaction identifier (TxID)
Throws: Session.commit(), TxID

rollback

void rollback(TxID id)
              throws TransactionCallbackException

Invoked when rolling back a Session transaction.

This method should be used to roll back any underlying transaction and return any underlying connection back to the pool. The TxID is provided to determine which transaction is being committed

Parameters:
id - transaction identifier (TxID)
Throws: Session.rollback(), TxID

isExternalTransactionActive

boolean isExternalTransactionActive(Session session)

Called when an application attempts to use a Session with no transaction active.

The callback could return true in which case an auto Session.begin() is executed. If false is returned, an application exception is thrown indicating no transaction is active. This event is usually used when integrating with a J2EE environment such as WebSphere Application Server.

Parameters:
session - the session which the application is using
Returns:
true if an auto begin should be done,


com.ibm.websphere.objectgrid.plugins
Interface TransactionCallback.BeforeCommit

All Superinterfaces:
TransactionCallback

Enclosing interface:
TransactionCallback

public static interface TransactionCallback.BeforeCommit
extends TransactionCallback

The BeforeCommit optional mix-in interface for the TransactionCallback plug-in interface allows plug-ins to be notified at the beginning of a Session.commit(). Implementations can use the beforeCommit() method to validate changed data in the transaction and modify the data.

Since:
7.1.1

Nested Class Summary
static interface TransactionCallback.BeforeCommit.TransactionContext
          The TransactionContext identifies various information that's available to the beforeCommit() method.
 
Nested classes/interfaces inherited from interface com.ibm.websphere.objectgrid.plugins.TransactionCallback

TransactionCallback.BeforeCommit
 
Method Summary
void beforeCommit(TransactionCallback.BeforeCommit.TransactionContext ctx)
          Invoked at the beginning of a Session.commit().
 
Methods inherited from interface com.ibm.websphere.objectgrid.plugins.TransactionCallback

begin, commit, initialize, isExternalTransactionActive, rollback
 

Method Detail

beforeCommit

void beforeCommit(TransactionCallback.BeforeCommit.TransactionContext ctx)
                  throws TransactionCallbackException

Invoked at the beginning of a Session.commit().

Use the TransactionContext.getLogSequences() method to retrieve the changes made by this transaction. Use the TransactionContext.getTxId().getSession() methods to access the Session. The Session can be used to access ObjectMaps and modify data in the current transaction.

Parameters:
ctx - the context of the transaction.
Throws: TxID


com.ibm.websphere.objectgrid.plugins
Interface TransactionCallback.BeforeCommit.TransactionContext

Enclosing interface:
TransactionCallback.BeforeCommit

public static interface TransactionCallback.BeforeCommit.TransactionContext

The TransactionContext identifies various information that's available to the beforeCommit() method.

Since:
7.1.1

Method Summary
java.util.Collection<LogSequence> getLogSequences()
          The LogSequences that reflect the pending changes to the map.
TxID getTxID()
          Retrieve the TxID for the transaction.
 

Method Detail

getTxID

TxID getTxID()

Retrieve the TxID for the transaction.

Returns:
the TxID for the transaction.

getLogSequences

java.util.Collection<LogSequence> getLogSequences()

The LogSequences that reflect the pending changes to the map.

Returns:
the LogSequences.


com.ibm.websphere.objectgrid.plugins
Class TransactionCallbackException

java.lang.Object
  ava.lang.Throwable
      ava.lang.Exception
          com.ibm.websphere.objectgrid.ObjectGridException
              com.ibm.websphere.objectgrid.plugins.TransactionCallbackException

All Implemented Interfaces:
IObjectGridException, java.io.Serializable

Direct Known Subclasses:
ClientServerTransactionCallbackException, ReplicationVotedToRollbackTransactionException

public class TransactionCallbackException
extends ObjectGridException

This exception is thrown when a method call to TransactionCallback fails.

Since:
WAS XD 6.0, XC10
Serialized Form

Constructor Summary
TransactionCallbackException()
          Constructs a new TransactionCallbackException with null as its detail message.
TransactionCallbackException(java.lang.String message)
          Constructs a new TransactionCallbackException with the specified detail message.
TransactionCallbackException(java.lang.String message, java.lang.Throwable cause)
          Constructs a new TransactionCallbackException with the specified detail message and cause.
TransactionCallbackException(java.lang.Throwable cause)
          Constructs a new TransactionCallbackException with a specified cause.
 
Method Summary
 
Methods inherited from class com.ibm.websphere.objectgrid.ObjectGridException

getCause, initCause
 
Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
 
Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

TransactionCallbackException

public TransactionCallbackException()

Constructs a new TransactionCallbackException with null as its detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

TransactionCallbackException

public TransactionCallbackException(java.lang.String message)

Constructs a new TransactionCallbackException with the specified detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

Parameters:
message - the detail message. The detail message is saved for later Throwable.getMessage()

TransactionCallbackException

public TransactionCallbackException(java.lang.String message,
                                    java.lang.Throwable cause)

Constructs a new TransactionCallbackException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this TransactionCallbackException's detail message.

Parameters:
message - the detail message (which is saved for later retrieval by the getMessage method).
cause - the cause (which is saved for later retrieval by the getCause method). (Anull value is permitted, and indicates that the cause is nonexistent or Throwable.getMessage()

TransactionCallbackException

public TransactionCallbackException(java.lang.Throwable cause)

Constructs a new TransactionCallbackException with a specified cause. The cause and a detail message of (cause==null ? null : cause.toString()) is used (which typically contains the class and detail message of cause). This constructor is useful for TransactionCallbackExceptions that are little more than wrappers for other throwables.

Parameters:
cause - is the exception that caused this exception to be thrown, which is saved for later retrieval by the getCause() method. A null value is permitted and indicates that the cause


com.ibm.websphere.objectgrid.plugins
Interface ValueProxyInfo

public interface ValueProxyInfo

This interface can be used by value objects to inform a BackingMap or Loader which attribute(s) have been dirtied. This mechanism allows the BackingMap and Loader to interrogate the set of changed attributes in the value object instead of just assuming the whole value object has been updated. For this to be useful, the application must only use the getter and setter methods defined for the value object's interface.

Since:
WAS XD 6.0, XC10
BackingMap.setCopyMode(CopyMode, Class), Loader#batchUpdate(TxID, LogSequence)

Method Summary
void ibmClearDirtyAttributes()
          Clears the list of dirty attributes.
java.util.List ibmGetDirtyAttributes()
          Returns a list of dirty attributes based on the value interface set on the map.
java.lang.Object ibmGetRealValue()
          Returns the real value object this proxy represents.
 

Method Detail

ibmGetDirtyAttributes

java.util.List ibmGetDirtyAttributes()

Returns a list of dirty attributes based on the value interface set on the map.

The attribute name is always starts with an upper case letter. For example, if the setter for the attribute is setPrice then 'Price' is the string returned here. The runtime uses substring(3) of the setter method name as the attribute name.

Returns:
List of attribute names (Strings)

ibmGetRealValue

java.lang.Object ibmGetRealValue()

Returns the real value object this proxy represents.

Needed internally by the BackingMap to return a separate proxy for each transaction.

Returns:
actual value object.

ibmClearDirtyAttributes

void ibmClearDirtyAttributes()

Clears the list of dirty attributes.


Package com.ibm.websphere.objectgrid.security

This package has the class MapPermission and class AdminPermission which represents the permissions for to access the ObjectGrid maps and ObjectGrid administration respectively.

See:
          Description

Class Summary
SecurityConstants
This class contains the constants used for security configuration.
 

Exception Summary
ObjectGridSecurityException
This exception represents a general ObjectGrid security exception.
 


Package com.ibm.websphere.objectgrid.security Description

This package has the class MapPermission and class AdminPermission which represents the permissions for to access the ObjectGrid maps and ObjectGrid administration respectively.


MapPermission action types.

The ObjectGrid defines 5 permission actions used to authorize accesses to the maps. These permissions allow access to maps to be controlled by an administrator. Objects within the ObjectGrid use a simple naming scheme. Each Map is named using the convention of the ObjectGrid name followed by a period followed by the Map name. For example, if the object grid name is "myObjectGrid" and the map name is "myMap", then the map name used in the permission is "myobjectgrid.mymap".

Wildcards can be used on names with some restrictions. A wild card "*" can be used to replace the map name or the object grid name, but not partially. For example, "myObjectGrid.*", "*.myMap", and "*.*" are valid names, but "myObject*.*" is not valid.

There are five actions with the permission object ObjectMapPermission.

  com.ibm.websphere.objectgrid.ObjectMap/
com.ibm.websphere.objectgrid.JavaMap
Read boolean containsKey(Object)
boolean equals(Object)
Object get(Object)
Object get(Object, Serializable)
List getAll(List)
List getAll(List keyList, Serializable)
List getAllForUpdate(List)
List getAllForUpdate(List, Serializable)
Object getForUpdate(Object)
Object getForUpdate(Object, Serializable)
write Object put(Object key, Object value)
void put(Object, Object, Serializable)
void putAll(Map)
void putAll(Map, Serializable)
void update(Object, Object)
void update(Object, Object, Serializable)
insert public void insert(Object, Object)
void insert(Object, Object, Serializable)
remove Object remove(Object)
void removeAll(Collection)
invalidate public void invalidate(Object, boolean)
void invalidateAll(Collection, boolean)
void invalidateUsingKeyword(Serializable, boolean)
int setTimeToLive(int)

An authroizationMechanism setting of the ObjectGrid has two possible values: JAAS and custom. Users can also use API ObjectGrid.setAuthorizationMechanism(int) to set which authorization mechanism the object grid will use.

A value "JAAS" means ObjectGrid will rely on JAAS authorization mechanism to handle the authorization. A JAAS policy file should be configured to associate permissions with a set of credentials and/or groups of credentials. We recommend that groups should be used as then new users can be added to groups without modifying the policy file.

A value "custom" means ObjectGrid will rely on custom authorization mechanism to handle the authorization. Users can set call ObjectGrid.setMapAuthorization(com.ibm.websphere.objectgrid.security.plugins.MapAuthorization) to set their custom authroization plug-in. Users can also configure the objectgrid.xml to achieve the same result.


AdminPermission types

An AdminPermission has two types: ADMIN and MONITOR. An AdminPermission with ADMIN name grants permissions to access all the ManagementMBean methods. An AdminPermission with MONITOR name grants permissions to access the ManagementMBean read-only methods. Therefore, ADMIN permission implies MONITOR permission.

The detailed operations granted to users with different permissions are listed in the following table. These operations correspond to the methods in the ManagementMBean interface:

operations admin monitor
startServer Y N
stopServer Y N
forceStopServer Y N
setServerTrace Y N
retrieveServerStatus Y Y
getMapStats Y Y
getOGStats Y Y
getReplicationStats Y Y

The table can read like this: If the client has admin permission, it can execute "startServer" task; if the client has monitor permission, it cannot execute "startServer" task.


AgentPermission types

An AgentPermission represents permissions to the datagrid agents. The name of the permission is the full name of the ObjectGrid map, and the action is a "," delimited string of agent implementation class names or package names.

The following methods in the class AgentManager requires AgentPermission:


ObjectGridPermission types

An ObjectGridPermission represents permissions to an ObjectGrid. The name of the permission is the ObjectGrid name, and the action is either "query", "streamquery" or "dynamicmap".

The detailed methods which require different permissions are listed in the following table:

methods action
Session.createObjectQuery(String) query
EntityManager.createQuery(String) query
StreamQuerySet.setDeployed(boolean) streamquery
Session.getMap(String) dynamicmap


ServerMapPermission types

An ServerMapPermission represents permissions to an ObjectMap hosted in a server. The name of the permission is the full name of the ObjectGrid map name, and the action is either "replicate" or "dynamicIndex".

The detailed methods which require different ServerMapPermission are listed in the following table:

methods action
ClientReplicableMap.enableClientReplication(Mode, int[], ReplicationMapListener) replicate
BackingMap.createDynamicIndex(String, boolean, String, DynamicIndexCallback) dynamicIndex
BackingMap.removeDynamicIndex(String) dynamicIndex

SecurityConstants

SecurityConstants class contains constants used for representing the security parameters.


Package com.ibm.websphere.objectgrid.security.plugins

This package contains the interfaces for adding plug-ins to the ObjectGrid security framework and assoicated Exception classes.

See:
          Description

Interface Summary
Credential
This interface represents a credential used by an ObjectGrid client.
CredentialGenerator
This plugin is used to get a Credential representing this client.
 

Exception Summary
CannotGenerateCredentialException
This exception indicates a credential cannot be generated.
ExpiredCredentialException
This exception indicates that the credential used for authentication is expired.
InvalidCredentialException
This exception indicates that the credential used for authentication is invalid.
 


Package com.ibm.websphere.objectgrid.security.plugins Description

This package contains the interfaces for adding plug-ins to the ObjectGrid security framework and assoicated Exception classes.

The plug-ins in this package are used for authentication and authorization. Below is a brief summary of these plug-ins.

Authentication plug-ins


Credential

A com.ibm.websphere.objectgrid.security.plug-ins.Credential plug-in represents a client credential. It is passed from the clien to server for authentication. It could be a user password pair, a kerberos ticket, etc.


CredentialGenerator

A com.ibm.websphere.objectgrid.security.plug-ins.CredentialGenerator plug-in is used to get a Credential representing this client. It is a factory for the Credential object.


Authenticator

com.ibm.websphere.objectgrid.security.plug-ins.Authenticator plug-in is used for an ObjectGrid client to authenticate to an ObjectGrid server.

SubjectSource

com.ibm.websphere.objectgrid.security.plug-ins.SubjectSource plug-in is used to get a Subject instance representing the ObjectGrid client. This plug-in is used when ObjectGrid security is on. The method getSubject is called by ObjectGrid runtime when ObjectGrid.getSession() method is used to get a session. This plug-in is normally used for a local ObjectGrid and provides a mechanism to plug in application server-specific way to retrieve a Subject object from the environment.

SubjectValidation

com.ibm.websphere.objectgrid.security.plug-ins.SubjectValidation plug-in is used to validate a Subject object passed to the ObjectGrid. A typical scenario where this plug-in can be used usually have the following characteristics:

The last bullet is usually the most difficult to satisify. This will require the support from the originator of the Subject object.

For example, when a ObjectGrid client is running in WebSphere Application Server (WAS) Extended Deployment (XD) which also hosts the ObjectGrid server. The client can retrieve the runAs Subject and then pass it to the ObjectGrid instance. The ObjectGrid Server will then invoke the SubjectValidation mechanism, which uses WAS-specific APIs to validate the Subject object has not been tampered with.

Authorization plug-ins


MapAuthorization

com.ibm.websphere.objectgrid.security.plug-ins.MapAuthorization plug-in is used to check whether the user represented by the Subject object has a speicfied ObjectMapPermission. Users can implement this interface to plug in their own authorization mechanism. For example, users can plug in their authorization mechanism, which uses Tivoli Access Manager Authorization Server .

Starting from WebSphere XD 6.1, MapAuthorization has been deprecated. Users can use ObjectGridAuthorization to authorize map accesses.


AdminAuthorization

com.ibm.websphere.objectgrid.security.plug-ins.AdminAuthorization plug-in can be used to authorize management operations to the principals contained in the Subject object. The permissions for the management operations are represented by AdminPermission objects.


ObjectGridAuthorization

com.ibm.websphere.objectgrid.security.plug-ins.ObjectGridAuthorization plug-in can be used to authorize ObjectGrid, ObjectMap and JavaMap accesses to the Principals represented by a Subject object. All access and operations to ObjectGrid can be authorized using this plug-in.


Other plug-ins


SecureTokenManager

This interface is used by ObjectGrid servers to transform an object to a secure token and vice versa. A secure token is a byte array.

For details about how to use these plug-ins, please refer to individual JavaDoc and ObjectGrid programming guide.


Package com.ibm.websphere.objectgrid.security.plugins.builtins Description

This package contains the built-in implementation for the security plugins.


com.ibm.websphere.objectgrid.security.plugins.builtins
Class UserPasswordCredential

java.lang.Object
  com.ibm.websphere.objectgrid.security.plugins.builtins.UserPasswordCredential

All Implemented Interfaces:
Credential, java.io.Serializable

public class UserPasswordCredential
extends java.lang.Object
implements Credential

This class represents a credential containing a user ID and password.

Since:
WAS XD 6.0.1, XC10
UserPasswordCredentialGenerator.getCredential(), Serialized Form

Constructor Summary
UserPasswordCredential(java.lang.String userName, java.lang.String password)
          Creates a UserPasswordCredential with the specified user name and password.
 
Method Summary
boolean equals(java.lang.Object o)
          Checks two UserPasswordCredential objects for equality.
java.lang.String getPassword()
          Gets the password for this credential.
java.lang.String getUserName()
          Gets the user name for this credential.
int hashCode()
          Returns the hashcode of the UserPasswordCredential object.
void setPassword(java.lang.String password)
          Sets the password for this credential.
void setUserName(java.lang.String userName)
          Sets the user name for this credential.
java.lang.String toString()
           
 
Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

UserPasswordCredential

public UserPasswordCredential(java.lang.String userName,
                              java.lang.String password)

Creates a UserPasswordCredential with the specified user name and password.

Parameters:
userName - the user name for this credential
password - the password for this credential
Throws:
java.lang.IllegalArgumentException - if userName or password is null
Method Detail

getUserName

public java.lang.String getUserName()

Gets the user name for this credential.

Returns:
the user name argument that was passed to the constructor or the setUserName(String)

setUserName

public void setUserName(java.lang.String userName)

Sets the user name for this credential.

Parameters:
userName - the user name to set.
Throws:
java.lang.IllegalArgumentException - if userName is null

getPassword

public java.lang.String getPassword()

Gets the password for this credential.

Returns:
the password argument that was passed to the constructor or the setPassword(String)

setPassword

public void setPassword(java.lang.String password)

Sets the password for this credential.

Parameters:
password - the password to set.
Throws:
java.lang.IllegalArgumentException - if password is null

equals

public boolean equals(java.lang.Object o)

Checks two UserPasswordCredential objects for equality.

Two UserPasswordCredential objects are equal if and only if their user names and passwords are equal.

Specified by:
equals in interface Credential
Overrides:
equals in class java.lang.Object

Parameters:
o - the object we are testing for equality with this object.

hashCode

public int hashCode()

Returns the hashcode of the UserPasswordCredential object.

Specified by:
hashCode in interface Credential
Overrides:
hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:
toString in class java.lang.Object

Returns:
the string presentation of the UserPasswordCredential object.


com.ibm.websphere.objectgrid.security.plugins.builtins
Class UserPasswordCredentialGenerator

java.lang.Object
  com.ibm.websphere.objectgrid.security.plugins.builtins.UserPasswordCredentialGenerator

All Implemented Interfaces:
CredentialGenerator

public class UserPasswordCredentialGenerator
extends java.lang.Object
implements CredentialGenerator

This credential generator creates UserPasswordCredential objects.

UserPasswordCredentialGenerator has a one to one relationship with UserPasswordCredential because it can only create a UserPasswordCredential representing one identity.

Since:
WAS XD 6.0.1, XC10
UserPasswordCredential

Constructor Summary
UserPasswordCredentialGenerator()
          Creates a UserPasswordCredentialGenerator with no user name or password.
UserPasswordCredentialGenerator(java.lang.String user, java.lang.String pwd)
          Creates a UserPasswordCredentialGenerator with a specified user name and password
 
Method Summary
boolean equals(java.lang.Object obj)
          Checks two UserPasswordCredentialGenerator objects for equality.
Credential getCredential()
          Creates a new UserPasswordCredential object using this object's user name and password.
java.lang.String getPassword()
          Gets the password for this credential generator.
java.lang.String getUserName()
          Gets the user name for this credential.
int hashCode()
          Returns the hashcode of the UserPasswordCredentialGenerator object.
void setProperties(java.lang.String properties)
          Sets additional properties namely a user name and password.
 
Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

UserPasswordCredentialGenerator

public UserPasswordCredentialGenerator()

Creates a UserPasswordCredentialGenerator with no user name or password.

UserPasswordCredentialGenerator

public UserPasswordCredentialGenerator(java.lang.String user,
                                       java.lang.String pwd)

Creates a UserPasswordCredentialGenerator with a specified user name and password

Parameters:
user - the user name
pwd - the password
Method Detail

getCredential

public Credential getCredential()

Creates a new UserPasswordCredential object using this object's user name and password.

Specified by:
getCredential in interface CredentialGenerator

UserPasswordCredential

getPassword

public java.lang.String getPassword()

Gets the password for this credential generator.

Returns:
the password argument that was passed to the constructor

getUserName

public java.lang.String getUserName()

Gets the user name for this credential.

Returns:
the user argument that was passed to the constructor of this class

setProperties

public void setProperties(java.lang.String properties)

Sets additional properties namely a user name and password.

Specified by:
setProperties in interface CredentialGenerator

Parameters:
properties - a properties string with a user name and a password separated by a blank.
Throws:
java.lang.IllegalArgumentException - if the format is not valid

equals

public boolean equals(java.lang.Object obj)

Checks two UserPasswordCredentialGenerator objects for equality.

Two UserPasswordCredentialGenerator objects are equal if and only if their user names and passwords are equal.

Overrides:
equals in class java.lang.Object

Parameters:
obj - the object we are testing for equality with this object.
Returns:
true if both UserPasswordCredentialGenerator objects are equivalent.

hashCode

public int hashCode()

Returns the hashcode of the UserPasswordCredentialGenerator object.

Overrides:
hashCode in class java.lang.Object

Returns:
the hash code of this object


com.ibm.websphere.objectgrid.security.plugins.builtins
Class WSTokenCredential

java.lang.Object
  com.ibm.websphere.objectgrid.security.plugins.builtins.WSTokenCredential

All Implemented Interfaces:
Credential, java.io.Serializable

public final class WSTokenCredential
extends java.lang.Object
implements Credential

This class represents a WebSphere Application Server security token credential. An instance of this class contains byte arrays which represent the security tokens used in the Application server. Specifically, this credential contains two tokens, a WebSphere specific authentication token and a WebSphere specific opaque authorization token.

Since:
WAS XD 6.0.1, XC10
Serialized Form

Constructor Summary
WSTokenCredential(byte[] at, byte[] oat)
          Creates a new WebSphere token credential with the specified security tokens.
 
Method Summary
boolean equals(java.lang.Object o)
          Checks two WSTokenCredential objects for equality.
byte[] getAT()
          Gets the authetication token for this credential.
byte[] getOAT()
          Gets the opaque authorization token for this credential.
int hashCode()
          Returns the hashcode of the WSTokenCredential object.
 
Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WSTokenCredential

public WSTokenCredential(byte[] at,
                         byte[] oat)

Creates a new WebSphere token credential with the specified security tokens.

Parameters:
at - the authentication token
oat - the opaque authorization token
Method Detail

getAT

public byte[] getAT()

Gets the authetication token for this credential.

Returns:
the authentication token argument that was passed to the constructor of this class

getOAT

public byte[] getOAT()

Gets the opaque authorization token for this credential.

Returns:
the opaque authorization token argument that was passed to the constructor of this class

equals

public boolean equals(java.lang.Object o)

Checks two WSTokenCredential objects for equality.

Two WSTokenCredential objects are equal if and only if their authentication tokens and opaque authorization tokens are equal.

Specified by:
equals in interface Credential
Overrides:
equals in class java.lang.Object

Parameters:
o - the object we are testing for equality with this object.

hashCode

public int hashCode()

Returns the hashcode of the WSTokenCredential object.

Specified by:
hashCode in interface Credential
Overrides:
hashCode in class java.lang.Object


com.ibm.websphere.objectgrid.security.plugins.builtins
Class WSTokenCredentialGenerator

java.lang.Object
  com.ibm.websphere.objectgrid.security.plugins.builtins.WSTokenCredentialGenerator

All Implemented Interfaces:
CredentialGenerator

public class WSTokenCredentialGenerator
extends java.lang.Object
implements CredentialGenerator

This class represents a credential generator when running in WebSphere Application Server.

When the getCredential() method is called, the Subject associated with the current thread is retrieved. The security information in this Subject object is converted into a WSTokenCredential. This credential object has enough information for the receiving side to rebuild the security context.

This scenario takes advantage of the fact that the ObjectGrid client has already been authenticated. Since application servers housing ObjectGrid servers are in the same security domain as the application servers housing the ObjectGrid clients, the security tokens can be propagated from the ObjectGrid client to the ObjectGrid server so there is no need to re-authenticate to the same user registry.

Users can specify whether to retrieve a runAs subject or a caller subject from the thread using the RUN_AS_SUBJECT or CALLER_SUBJECT constant.

WSTokenCredentialGenerator has a one to many relationship with WSTokenCredential because it can generate different WSTokenCredential objects based on what Subject is associated with the current thread.

Since:
WAS XD 6.0.1, XC10

Field Summary
static int CALLER_SUBJECT
          A constant representing the caller Subject type
static java.lang.String CALLER_SUBJECT_STRING
          A constant representing the caller Subject type
static int RUN_AS_SUBJECT
          A constant representing the runAs Subject type
static java.lang.String RUN_AS_SUBJECT_STRING
          A constant representing the runAs Subject type
 
Constructor Summary
WSTokenCredentialGenerator()
          Creates a new WSTokenCredentialGenerator with a default runAs subject type.
WSTokenCredentialGenerator(int aType)
          Creates a new WSTokenCredentialGenerator with the specified subject type.
 
Method Summary
Credential getCredential()
          Creates a new WSTokenCredential object using this object's using the security information from the Subject associated with the current thread.
int getType()
          Gets the subject type.
void setProperties(java.lang.String properties)
          Sets additional properties namely the subject type.
void setType(int aType)
          Sets the subject type, either RUN_AS_SUBJECT or CALLER_SUBJECT.
 
Methods inherited from class java.lang.Object

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

Field Detail

RUN_AS_SUBJECT

public static final int RUN_AS_SUBJECT

A constant representing the runAs Subject type

CALLER_SUBJECT

public static final int CALLER_SUBJECT

A constant representing the caller Subject type

RUN_AS_SUBJECT_STRING

public static final java.lang.String RUN_AS_SUBJECT_STRING

A constant representing the runAs Subject type

CALLER_SUBJECT_STRING

public static final java.lang.String CALLER_SUBJECT_STRING

A constant representing the caller Subject type

Constructor Detail

WSTokenCredentialGenerator

public WSTokenCredentialGenerator()

Creates a new WSTokenCredentialGenerator with a default runAs subject type.

setProperties(String), setType(int)

WSTokenCredentialGenerator

public WSTokenCredentialGenerator(int aType)

Creates a new WSTokenCredentialGenerator with the specified subject type.

A valid subject type is either RUN_AS_SUBJECT or CALLER_SUBJECT.

Parameters:
aType - either RUN_AS_SUBJECT or CALLER_SUBJECT
Throws: RUN_AS_SUBJECT
Method Detail

getCredential

public Credential getCredential()
                         throws CannotGenerateCredentialException

Creates a new WSTokenCredential object using this object's using the security information from the Subject associated with the current thread.

Specified by:
getCredential in interface CredentialGenerator

Returns:
a new WSTokenCredential instance
Throws:
CannotGenerateCredentialException - if an error occurs during retrieval of the Subject's security information, see the cause WSTokenCredential

getType

public int getType()

Gets the subject type.

Returns:
the argument that was passed to the constructor or the setType(int) method, the value from the argument passed to the setProperties method, or the default value of RUN_AS_SUBJECT setProperties(String), setType(int)

setType

public void setType(int aType)

Sets the subject type, either RUN_AS_SUBJECT or CALLER_SUBJECT.

Parameters:
aType - the subject type
Throws:
java.lang.IllegalArgumentException - if the specified type is invalid

setProperties

public void setProperties(java.lang.String properties)

Sets additional properties namely the subject type.

Specified by:
setProperties in interface CredentialGenerator

Parameters:
properties - the property should be either RUN_AS_SUBJECT_STRING or CALLER_SUBJECT_STRING
Throws:
java.lang.IllegalArgumentException - if properties is not one of the expected RUN_AS_SUBJECT_STRING


com.ibm.websphere.objectgrid.security.plugins
Class CannotGenerateCredentialException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          com.ibm.websphere.objectgrid.ObjectGridException
              com.ibm.websphere.objectgrid.security.ObjectGridSecurityException
                  com.ibm.websphere.objectgrid.security.plugins.CannotGenerateCredentialException

All Implemented Interfaces:
IObjectGridException, java.io.Serializable

public class CannotGenerateCredentialException
extends ObjectGridSecurityException

This exception indicates a credential cannot be generated.

Since:
WAS XD 6.0.1, XC10
Serialized Form

Constructor Summary
CannotGenerateCredentialException()
          Constructs a new CannotGenerateCredentialException with null as its detail message.
CannotGenerateCredentialException(java.lang.String message)
          Constructs a new CannotGenerateCredentialException with the specified detail message.
CannotGenerateCredentialException(java.lang.String message, java.lang.Throwable cause)
          Constructs a new CannotGenerateCredentialException with the specified detail message and cause.
CannotGenerateCredentialException(java.lang.Throwable cause)
          Constructs a new CannotGenerateCredentialException with a specified cause.
 
Method Summary
 
Methods inherited from class com.ibm.websphere.objectgrid.ObjectGridException

getCause, initCause
 
Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
 
Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

CannotGenerateCredentialException

public CannotGenerateCredentialException()

Constructs a new CannotGenerateCredentialException with null as its detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

CannotGenerateCredentialException

public CannotGenerateCredentialException(java.lang.String message)

Constructs a new CannotGenerateCredentialException with the specified detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

Parameters:
message - the detail message. The detail message is saved for later Throwable.getMessage()

CannotGenerateCredentialException

public CannotGenerateCredentialException(java.lang.String message,
                                         java.lang.Throwable cause)

Constructs a new CannotGenerateCredentialException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this CannotGenerateCredentialException's detail message.

Parameters:
message - the detail message (which is saved for later retrieval by the getMessage method).
cause - the cause (which is saved for later retrieval by the getCause method). (Anull value is permitted, and indicates that the cause is nonexistent or Throwable.getMessage()

CannotGenerateCredentialException

public CannotGenerateCredentialException(java.lang.Throwable cause)

Constructs a new CannotGenerateCredentialException with a specified cause. The cause and a detail message of (cause==null ? null : cause.toString()) is used (which typically contains the class and detail message of cause). This constructor is useful for CannotGenerateCredentialExceptions that are little more than wrappers for other throwables.

Parameters:
cause - is the exception that caused this exception to be thrown, which is saved for later retrieval by the getCause() method. A null value is permitted and indicates that the cause


com.ibm.websphere.objectgrid.security.plugins
Interface Credential

All Superinterfaces:
java.io.Serializable

All Known Implementing Classes:
UserPasswordCredential, WSTokenCredential

public interface Credential
extends java.io.Serializable

This interface represents a credential used by an ObjectGrid client. An instance of this class represents one client indentity. This credential will be sent to the ObjectGrid server for authentication. It should be serializable.

A credential has to implement the equals(Object) and hashCode() methods. Two Credential objects are considered equal if and only if they represent the same identity and security information. For example, if the credential contains a user ID and password. Two credentials are equal if and only if both their user IDs and passwords are equal.

ObjectGrid provides three built-in implementations for this interface:

  • com.ibm.websphere.objectgrid.security.plugins.builtins.ClientCertificateCredential: A credential containing an SSL certificate chain.
  • com.ibm.websphere.objectgrid.security.plugins.builtins.UserPasswordCredential: A credential containing a user ID and password pair.
  • com.ibm.websphere.objectgrid.security.plugins.builtins.WSTokenCredential: A credential containing WebSphere Application Server specific authentication and authorization tokens.

Refer to the respective JavaDoc for more details.

Since:
WAS XD 6.0.1, XC10

Method Summary
boolean equals(java.lang.Object o)
          Checks two Credential objects for equality.
int hashCode()
          Returns the hashcode of the Credential object
 

Method Detail

equals

boolean equals(java.lang.Object o)

Checks two Credential objects for equality.

Two Credential objects are considered equal if and only if they represent the same identity and security information.

Overrides:
equals in class java.lang.Object

Parameters:
o - the object we are testing for equality with this object.
Returns:
true if both Credential objects are equivalent.

hashCode

int hashCode()

Returns the hashcode of the Credential object

Overrides:
hashCode in class java.lang.Object

Returns:
the hash code of the Credential object


com.ibm.websphere.objectgrid.security.plugins
Interface CredentialGenerator

All Known Implementing Classes:
UserPasswordCredentialGenerator, WSTokenCredentialGenerator

public interface CredentialGenerator

This plugin is used to get a Credential representing this client. It is a factory for the Credential object.

One example implementation is to return a Credential object containing a user ID and password pair. The implementation of the Credential generated by an implementation of this class must to be understood by the server's Authenticator plugin.

An implementation class of this interface should have a default constructor. Users can set the implementation class name (credentialGeneratorClass) in the client security configuration property file. The client runtime constructs an object of this implementation class and calls getCredential() to get the Credential to connect to an ObjectGrid cluster.

Users can also specify the addtional properties for this factory using the credentialGeneratorProps property in the client security configuration property file. These properties will be passed to this factory by calling the setProperties(String) method. This way, we can customize the CredentialGenerator factory.

Users can also set CredentialGenerator programmatically by calling ClientSecurityCinfiguration.setCredentialGenerator(CredentialGenerator) method.

For example, we can have the following settings in the client security configuration property file:

  • credentialGeneratorClass=com.myco.CredGenFactory
  • credentialGeneratorProps=user1 password1

A String "user1 password1" is passed to the setProperties(String) method, with the "user1" indicating the user name, and "password1" indicating the password.

ObjectGrid provides two built-in implementations for this interface:

  • com.ibm.websphere.objectgrid.security.plugins.builtins.UserPasswordCredentialGenerator: A credential generator generating a UserPasswordCredential containing a user ID and password pair.
  • com.ibm.websphere.objectgrid.security.plugins.builtins.WSTokenCredentialGenerator: A credential generator generating a WSTokenCredential containing WebSphere Application Server specific authentication and authorization tokens.

The relationship between CredentialGenerator and Credential can be one to one relationship or one to many relationship. For example. the UserPasswordCredentialGenerator has a one to one relationship with UserPasswordCredential, but the WSTokenCredentialGenerator has a one to many relationship with WSTokenCredential because it could generate different WSTokenCredential based on what Subject is associated with the current thread.

Refer to the respective JavaDoc for more details.

Since:
WAS XD 6.0.1, XC10
ClientSecurityConfiguration.setCredentialGenerator(CredentialGenerator), Credential, ObjectGrid.getSession(CredentialGenerator)

Method Summary
Credential getCredential()
          Gets a Credential which represents the client.
void setProperties(java.lang.String properties)
          Set the user defined properties to the factory.
 

Method Detail

getCredential

Credential getCredential()
                         throws CannotGenerateCredentialException

Gets a Credential which represents the client.

Returns:
the Credential representing the client
Throws:
CannotGenerateCredentialException - if a failure occurs when

setProperties

void setProperties(java.lang.String properties)

Set the user defined properties to the factory.

This method is used to set CredentialGenerator properties to the object. These properties can be set using the credentialGeneratorProps property in the client security configuration property file. This way, we can customize your factory.

Parameters:
properties - user defined properties


com.ibm.websphere.objectgrid.security.plugins
Class ExpiredCredentialException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          com.ibm.websphere.objectgrid.ObjectGridException
              com.ibm.websphere.objectgrid.security.ObjectGridSecurityException
                  com.ibm.websphere.objectgrid.security.plugins.ExpiredCredentialException

All Implemented Interfaces:
IObjectGridException, java.io.Serializable

public class ExpiredCredentialException
extends ObjectGridSecurityException

This exception indicates that the credential used for authentication is expired.

Since:
WAS XD 6.0.1, XC10
Serialized Form

Constructor Summary
ExpiredCredentialException()
          Constructs a new ExpiredCredentialException with null as its detail message.
ExpiredCredentialException(java.lang.String message)
          Constructs a new ExpiredCredentialException with the specified detail message.
ExpiredCredentialException(java.lang.String message, java.lang.Throwable cause)
          Constructs a new ExpiredCredentialException with the specified detail message and cause.
ExpiredCredentialException(java.lang.Throwable cause)
          Constructs a new ExpiredCredentialException with a specified cause.
 
Method Summary
 
Methods inherited from class com.ibm.websphere.objectgrid.ObjectGridException

getCause, initCause
 
Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
 
Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ExpiredCredentialException

public ExpiredCredentialException()

Constructs a new ExpiredCredentialException with null as its detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

ExpiredCredentialException

public ExpiredCredentialException(java.lang.String message)

Constructs a new ExpiredCredentialException with the specified detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

Parameters:
message - the detail message. The detail message is saved for later Throwable.getMessage()

ExpiredCredentialException

public ExpiredCredentialException(java.lang.String message,
                                  java.lang.Throwable cause)

Constructs a new ExpiredCredentialException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this ExpiredCredentialException's detail message.

Parameters:
message - the detail message (which is saved for later retrieval by the getMessage method).
cause - the cause (which is saved for later retrieval by the getCause method). (Anull value is permitted, and indicates that the cause is nonexistent or Throwable.getMessage()

ExpiredCredentialException

public ExpiredCredentialException(java.lang.Throwable cause)

Constructs a new ExpiredCredentialException with a specified cause. The cause and a detail message of (cause==null ? null : cause.toString()) is used (which typically contains the class and detail message of cause). This constructor is useful for ExpiredCredentialExceptions that are little more than wrappers for other throwables.

Parameters:
cause - is the exception that caused this exception to be thrown, which is saved for later retrieval by the getCause() method. A null value is permitted and indicates that the cause


com.ibm.websphere.objectgrid.security.plugins
Class InvalidCredentialException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          com.ibm.websphere.objectgrid.ObjectGridException
              com.ibm.websphere.objectgrid.security.ObjectGridSecurityException
                  com.ibm.websphere.objectgrid.security.plugins.InvalidCredentialException

All Implemented Interfaces:
IObjectGridException, java.io.Serializable

public class InvalidCredentialException
extends ObjectGridSecurityException

This exception indicates that the credential used for authentication is invalid.

Since:
WAS XD 6.0.1, XC10
Serialized Form

Constructor Summary
InvalidCredentialException()
          Constructs a new InvalidCredentialException with null as its detail message.
InvalidCredentialException(java.lang.String message)
          Constructs a new InvalidCredentialException with the specified detail message.
InvalidCredentialException(java.lang.String message, java.lang.Throwable cause)
          Constructs a new InvalidCredentialException with the specified detail message and cause.
InvalidCredentialException(java.lang.Throwable cause)
          Constructs a new InvalidCredentialException with a specified cause.
 
Method Summary
 
Methods inherited from class com.ibm.websphere.objectgrid.ObjectGridException

getCause, initCause
 
Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
 
Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

InvalidCredentialException

public InvalidCredentialException()

Constructs a new InvalidCredentialException with null as its detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

InvalidCredentialException

public InvalidCredentialException(java.lang.String message)

Constructs a new InvalidCredentialException with the specified detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

Parameters:
message - the detail message. The detail message is saved for later Throwable.getMessage()

InvalidCredentialException

public InvalidCredentialException(java.lang.String message,
                                  java.lang.Throwable cause)

Constructs a new InvalidCredentialException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this InvalidCredentialException's detail message.

Parameters:
message - the detail message (which is saved for later retrieval by the getMessage method).
cause - the cause (which is saved for later retrieval by the getCause method). (Anull value is permitted, and indicates that the cause is nonexistent or Throwable.getMessage()

InvalidCredentialException

public InvalidCredentialException(java.lang.Throwable cause)

Constructs a new InvalidCredentialException with a specified cause. The cause and a detail message of (cause==null ? null : cause.toString()) is used (which typically contains the class and detail message of cause). This constructor is useful for InvalidCredentialExceptions that are little more than wrappers for other throwables.

Parameters:
cause - is the exception that caused this exception to be thrown, which is saved for later retrieval by the getCause() method. A null value is permitted and indicates that the cause


Package com.ibm.websphere.objectgrid.security.config

This package contains the ObjectGrid client security configurations.

See:
          Description

Interface Summary
ClientSecurityConfiguration
This interface represents the client side security configurations.
SSLConfiguration
This interface represents an SSL Configuration.
 

Class Summary
ClientSecurityConfigurationFactory
This class is a factory class for creating ClientSecurityConfiguration and SSLConfiguration objects.
 


Package com.ibm.websphere.objectgrid.security.config Description

This package contains the ObjectGrid client security configurations.


ClientSecurityConfiguration

ClientSecurityConfiguration represents the client side security configurations. User can call ClientSecurityConfigurationFactory.getClientSecurityConfiguration to get a ClientSecurityConfiguration instance and then use setters to set the configuration properties.


SSLConfiguration

This interface represents a client side SSL Configuration. Users can call ClientSecurityConfigurationFactory.getSSLConfiguration to get an instance of SSLConfiguration and then use setters to set its configuration properties.


ClientSecurityConfigurationFactory

ClientSecurityConfigurationFactory is a factory to create ClientSecurityConfiguration and SSLConfiguration instances.


com.ibm.websphere.objectgrid.security.config
Interface ClientSecurityConfiguration

All Superinterfaces:
java.io.Serializable

public interface ClientSecurityConfiguration
extends java.io.Serializable

This interface represents the client side security configurations. User can call ClientSecurityConfigurationFactory.getClientSecurityConfiguration() to get a ClientSecurityConfiguration instance.

Users are not recommended to implement this interface in case more methods are added in future releases.

Since:
WAS XD 6.0.1, XC10
ObjectGridManager.connect(String, HostPortConnectionAttributes[], ClientSecurityConfiguration, URL), ObjectGridManager.connect(String, String, String, ClientSecurityConfiguration, URL), ObjectGridManager.connect(URL, String, ClientSecurityConfiguration, URL)

Method Summary
int getAuthenticationRetryCount()
          Gets the authentication retry count for this client security configuration.
int getClientCertificateAuthentication()
          Gets the client certificate authentication type for this client security configuration.
int getCredentialAuthenticationType()
          Gets the credential authentication type for this client security configuration.
CredentialGenerator getCredentialGenerator()
          Gets the CredentialGenerator object for this client security configuration.
java.lang.String getCredentialGeneratorClass()
          Gets the CredentialGenerator implementation class name set in the client security property file.
java.lang.String getCredentialGeneratorProps()
          Gets the CredentialGenerator properties set in the client security property file.
SSLConfiguration getSSLConfiguration()
          Gets the SSLConfiguration object associated with this client security configuration.
int getTransportType()
          Gets the transport type for this client security configuration.
boolean isSecurityEnabled()
          Gets whether security is enabled for this client security configuration.
boolean isSingleSignOnEnabled()
          Gets whether single sign on is enabled for this client security configuration.
void setAuthenticationRetryCount(int authenticationRetryCount)
          Sets the authentication retry count for this client security configuration.
void setClientCertificateAuthentication(int clientCertAuthen)
          Set the client certificate authentication type for this client security configuration.
void setCredentialAuthenticationType(int credAuthen)
          Sest the credential authentication type for this client security configuration.
void setCredentialGenerator(CredentialGenerator generator)
          Sets the CredentialGenerator object for this client security configuration.
void setSecurityEnabled(boolean isSecurityEnabled)
          Sets whether or not security is enabled for this client security configuration.
void setSingleSignOnEnabled(boolean enabled)
          Sets whether or not single sign on is enabled for this client security configuration.
void setSSLConfiguration(SSLConfiguration sslConfig)
          Sets the SSLConfiguration object associated with this client security configuration.
void setTransportType(int type)
          Sets the transport type for this client security configuration.
 

Method Detail

getAuthenticationRetryCount

int getAuthenticationRetryCount()

Gets the authentication retry count for this client security configuration.

The authentication retry count is the number a times authentication will be reattempted if there is a failure during authentication indicating the credential is expired.

Returns:
the argument that was passed to the setAuthenticationRetryCount(int) method of this interface or 0 if setAuthenticationRetryCount

setAuthenticationRetryCount

void setAuthenticationRetryCount(int authenticationRetryCount)

Sets the authentication retry count for this client security configuration.

Parameters:
authenticationRetryCount - the authentication retry count
Throws:
java.lang.IllegalArgumentException - if authenticationRetryCount is less than zero

getTransportType

int getTransportType()

Gets the transport type for this client security configuration.

The return value will be one of the three transport types defined on the SecurityConstants class.

Returns:
the argument that was passed to the setTransportType(int) method of this interface or SecurityConstants.SSL_SUPPORTED if setTransportType SecurityConstants.TCP_IP, SecurityConstants.SSL_SUPPORTED, SecurityConstants.SSL_REQUIRED

getClientCertificateAuthentication

int getClientCertificateAuthentication()

Gets the client certificate authentication type for this client security configuration.

Returns:
the argument that was passed to the setClientCertificateAuthentication(int) method of this interface or SecurityConstants.CLIENT_CERTIFICATE_AUTHENTICATION_SUPPORTED if setClientCertificateAuthentication was not SecurityConstants.CLIENT_CERTIFICATE_AUTHENTICATION_NEVER, SecurityConstants.CLIENT_CERTIFICATE_AUTHENTICATION_SUPPORTED, SecurityConstants.CLIENT_CERTIFICATE_AUTHENTICATION_REQUIRED

isSecurityEnabled

boolean isSecurityEnabled()

Gets whether security is enabled for this client security configuration.

Returns:
the argument that was passed to the setSecurityEnabled(boolean) method of this interface or false if setSecurityEnabled was not

isSingleSignOnEnabled

boolean isSingleSignOnEnabled()

Gets whether single sign on is enabled for this client security configuration.

Returns:
the argument that was passed to the setSingleSignOnEnabled(boolean) method of this interface or false if setSingleSignOnEnabled was not

setClientCertificateAuthentication

void setClientCertificateAuthentication(int clientCertAuthen)

Set the client certificate authentication type for this client security configuration.

Parameters:
clientCertAuthen - the client ceritificate authentication type
Throws: SecurityConstants.CLIENT_CERTIFICATE_AUTHENTICATION_SUPPORTED, SecurityConstants.CLIENT_CERTIFICATE_AUTHENTICATION_REQUIRED

setTransportType

void setTransportType(int type)

Sets the transport type for this client security configuration.

Parameters:
type - the transport type
Throws:
java.lang.IllegalArgumentException - if type is not one of the valid SecurityConstants.SSL_SUPPORTED, SecurityConstants.SSL_REQUIRED

setSecurityEnabled

void setSecurityEnabled(boolean isSecurityEnabled)

Sets whether or not security is enabled for this client security configuration.

Parameters:
isSecurityEnabled - whether or not security is enabled

setSingleSignOnEnabled

void setSingleSignOnEnabled(boolean enabled)

Sets whether or not single sign on is enabled for this client security configuration.

Parameters:
enabled - whether or not single sign on is enabled

getSSLConfiguration

SSLConfiguration getSSLConfiguration()

Gets the SSLConfiguration object associated with this client security configuration.

Returns:
the argument that was passed to the setSSLConfiguration(SSLConfiguration) method of this interface or null if setSSLConfiguration was not SSLConfiguration

setSSLConfiguration

void setSSLConfiguration(SSLConfiguration sslConfig)

Sets the SSLConfiguration object associated with this client security configuration.

getCredentialAuthenticationType

int getCredentialAuthenticationType()

Gets the credential authentication type for this client security configuration.

Returns:
the argument that was passed to the setCredentialAuthenticationType(int) method of this interface or SecurityConstants.CREDENTIAL_AUTHENTICATION_SUPPORTED if setCredentialAuthenticationType was not SecurityConstants.CREDENTIAL_AUTHENTICATION_NEVER, SecurityConstants.CREDENTIAL_AUTHENTICATION_SUPPORTED, SecurityConstants.CREDENTIAL_AUTHENTICATION_REQUIRED

setCredentialAuthenticationType

void setCredentialAuthenticationType(int credAuthen)

Sest the credential authentication type for this client security configuration.

Parameters:
credAuthen - the credential authentication type
Throws: SecurityConstants.CREDENTIAL_AUTHENTICATION_SUPPORTED, SecurityConstants.CREDENTIAL_AUTHENTICATION_REQUIRED

setCredentialGenerator

void setCredentialGenerator(CredentialGenerator generator)

Sets the CredentialGenerator object for this client security configuration.

getCredentialGenerator

CredentialGenerator getCredentialGenerator()

Gets the CredentialGenerator object for this client security configuration.

Returns:
the argument that was passed to the setCredentialGenerator(CredentialGenerator) method of this interface or null if setCredentialGenerator was not CredentialGenerator

getCredentialGeneratorClass

java.lang.String getCredentialGeneratorClass()

Gets the CredentialGenerator implementation class name set in the client security property file.

If the "credentialGeneratorClass" property is not set in the security property file, a null will be returned.

Returns:
the value of the "credentialGeneratorClass" from the client security property file. null is returned if no value

getCredentialGeneratorProps

java.lang.String getCredentialGeneratorProps()

Gets the CredentialGenerator properties set in the client security property file.

If the "credentialGeneratorProps" property is not set in the security security property file, a null will be returned.

If the "credentialGeneratorProps" property is set, but the property "credentialGeneratorClass" is not set, the "credentialGeneratorProps" property will be ignored. In this case, a null will be returned by this method.

Returns:
the value of the "credentialGeneratorProps" property from the client security property file. null is returned if no value is set for this property or for the


com.ibm.websphere.objectgrid.security.config
Class ClientSecurityConfigurationFactory

java.lang.Object
  com.ibm.websphere.objectgrid.security.config.ClientSecurityConfigurationFactory


public class ClientSecurityConfigurationFactory
extends java.lang.Object

This class is a factory class for creating ClientSecurityConfiguration and SSLConfiguration objects.

Since:
WAS XD 6.0.1, XC10
SSLConfiguration

Constructor Summary
ClientSecurityConfigurationFactory()
           
 
Method Summary
static ClientSecurityConfiguration getClientSecurityConfiguration()
          Creates a new client security configuration with all its attributes set to their default values.
static ClientSecurityConfiguration getClientSecurityConfiguration(java.util.Properties props)
          Creates a new client security configuration based on a Properties object.
static ClientSecurityConfiguration getClientSecurityConfiguration(java.lang.String fileName)
          Creates a new client security configuration based on a client security property file.
static SSLConfiguration getSSLConfiguration()
          Creates a new SSL configuration with all its attributes set to their default values.
static SSLConfiguration getSSLConfiguration(java.lang.String alias, java.lang.String jsseProvider, java.lang.String keyStoreName, java.lang.String keyStoreType, java.lang.String keyStorePassword, java.lang.String trustStoreName, java.lang.String trustStoreType, java.lang.String trustStorePassword, java.lang.String protocol)
          Creates a new SSL configuration using the specified attributes.
 
Methods inherited from class java.lang.Object

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

Constructor Detail

ClientSecurityConfigurationFactory

public ClientSecurityConfigurationFactory()

Method Detail

getSSLConfiguration

public static SSLConfiguration getSSLConfiguration()

Creates a new SSL configuration with all its attributes set to their default values.

SSLConfiguration

getSSLConfiguration

public static SSLConfiguration getSSLConfiguration(java.lang.String alias,
                                                   java.lang.String jsseProvider,
                                                   java.lang.String keyStoreName,
                                                   java.lang.String keyStoreType,
                                                   java.lang.String keyStorePassword,
                                                   java.lang.String trustStoreName,
                                                   java.lang.String trustStoreType,
                                                   java.lang.String trustStorePassword,
                                                   java.lang.String protocol)

Creates a new SSL configuration using the specified attributes.

Parameters:
alias - the key alias in the key store
jsseProvider - the JSSE provider
keyStoreName - the key store file path name
keyStoreType - format of the key store
keyStorePassword - the password to the key store
trustStoreName - the trust store file path name
trustStoreType - the format of the trust store
trustStorePassword - the password to the trust store
protocol - the SSL protocol
Returns:
a new SSLConfiguration instance
Throws:
java.lang.IllegalArgumentException - if keyStoreName or trustStoreName are SSLConfiguration

getClientSecurityConfiguration

public static ClientSecurityConfiguration getClientSecurityConfiguration()

Creates a new client security configuration with all its attributes set to their default values.

getClientSecurityConfiguration

public static ClientSecurityConfiguration getClientSecurityConfiguration(java.lang.String fileName)

Creates a new client security configuration based on a client security property file.

Parameters:
fileName - a security property file name
Returns:
a new ClientSecurityConfiguration instance
Throws:
java.lang.IllegalArgumentException - if there are attributes in the Properties

getClientSecurityConfiguration

public static ClientSecurityConfiguration getClientSecurityConfiguration(java.util.Properties props)

Creates a new client security configuration based on a Properties object.

Parameters:
props - a Properties object
Returns:
a new ClientSecurityConfiguration instance
Throws:
java.lang.IllegalArgumentException - if there are attributes in the Properties


com.ibm.websphere.objectgrid.security.config
Interface SSLConfiguration

All Superinterfaces:
java.io.Serializable

public interface SSLConfiguration
extends java.io.Serializable

This interface represents an SSL Configuration. Users can call ClientSecurityConfigurationFactory.getSSLConfiguration() to get an instance of SSLConfiguration.

An SSL configuration contains the following properties:

  • alias: the alias in the key store to represent the client
  • protocol: the SSL protocol
  • certReqSubjectDN: the required Subject DN in the peer certificate
  • contextProvider: the JSSE context provider
  • keyStore: the key store file name
  • keyStoreType: the key store file format
  • keyStorePassword: the password to protect the key store file
  • trustStore: the trust store file name
  • trustStoreType: the trust store file format
  • trustStorePassword: the password to protect the trust store file

Users are not recommended to implement this interface in case more methods are added in future releases.

Since:
WAS XD 6.0.1, XC10

Method Summary
boolean equals(SSLConfiguration config)
          Checks two SSLConfiguration objects for equality.
java.lang.String getAlias()
          Gets the SSL alias name for this SSL configuration.
java.lang.String getCertReqSubjectDN()
          Gets the required subject DN in the peer certificate for this SSL configuration.
java.lang.String getContextProvider()
          Gets the JSSE context provider for this SSL configuration.
java.lang.String getKeyStore()
          Gets the key store file path name for this SSL configuration.
java.lang.String getKeyStorePassword()
          Gets the password of the key store for this SSL configuration.
java.lang.String getKeyStoreType()
          Gets the type of the key store for this SSL configuration.
java.lang.String getProtocol()
          Gets the SSL protocol for this SSL configuration.
java.lang.String getTrustStore()
          Gets the trust store file path name for this SSL configuration.
java.lang.String getTrustStorePassword()
          Gets the password of the trust store for this SSL configuration.
java.lang.String getTrustStoreType()
          Gets the type of the trust store for this SSL configuration.
void setAlias(java.lang.String alias)
          Sets the SSL alias name for this SSL configuration.
void setCertReqSubjectDN(java.lang.String subjectDN)
          Sets the required subject DN in the peer certificate for this SSL configuration.
void setContextProvider(java.lang.String contextProvider)
          Sets the JSSE context provider for this SSL configuration.
void setKeyStore(java.lang.String keyStore)
          Sets the key store file path name for this SSL configuration.
void setKeyStorePassword(java.lang.String keyStorePassword)
          Sets the password of the key store for this SSL configuration.
void setKeyStoreType(java.lang.String keyStoreType)
          Sets the type of key store for this SSL configuration.
void setProtocol(java.lang.String protocol)
          Sets the SSL protocol for this SSL configuration.
void setTrustStore(java.lang.String trustStore)
          Sets the trust store file path name for this SSL configuration.
void setTrustStorePassword(java.lang.String trustStorePassword)
          Sets the password of the trust store for this SSL configuration.
void setTrustStoreType(java.lang.String trustStoreType)
          Sets the type of the trust store for this SSL configuration.
 

Method Detail

getAlias

java.lang.String getAlias()

Gets the SSL alias name for this SSL configuration.

Returns:
the argument that was passed to the setAlias(String) method of this interface or null if

setAlias

void setAlias(java.lang.String alias)

Sets the SSL alias name for this SSL configuration.

Parameters:
alias - the SSL alias name

getProtocol

java.lang.String getProtocol()

Gets the SSL protocol for this SSL configuration.

Returns:
the argument that was passed to the setProtocol(String) method of this interface or null if

setProtocol

void setProtocol(java.lang.String protocol)

Sets the SSL protocol for this SSL configuration.

An SSL protocol can be SSL, TLS, SSLv2, SSLv3, etc., depending on which JDK is being used.

Parameters:
protocol - the SSL protocol

getContextProvider

java.lang.String getContextProvider()

Gets the JSSE context provider for this SSL configuration.

Returns:
the argument that was passed to the setContextProvider(String) method of this interface or null if setContextProvider was not

setContextProvider

void setContextProvider(java.lang.String contextProvider)

Sets the JSSE context provider for this SSL configuration.

A JSSE context provider can be SunJSSE, IBMJSSE, IBMJSSE2, etc., depending on which JDK is being used.

Parameters:
contextProvider - the SSL context provider

getKeyStore

java.lang.String getKeyStore()

Gets the key store file path name for this SSL configuration.

Returns:
the absolute path of the argument that was passed to the setKeyStore(String) method of this interface or null if setKeyStore was not

setKeyStore

void setKeyStore(java.lang.String keyStore)

Sets the key store file path name for this SSL configuration.

A keystore maintains the private key of an entity, as well as its corresponding public key certificates.

Parameters:
keyStore - the file path name of a keystore file
Throws:
java.lang.IllegalArgumentException - if keyStore is null setKeyStoreType(String)

getKeyStorePassword

java.lang.String getKeyStorePassword()

Gets the password of the key store for this SSL configuration.

Returns:
the argument that was passed to the setKeyStorePassword(String) method of this interface or null if setKeyStorePassword was not

setKeyStorePassword

void setKeyStorePassword(java.lang.String keyStorePassword)

Sets the password of the key store for this SSL configuration.

setKeyStoreType(String)

getKeyStoreType

java.lang.String getKeyStoreType()

Gets the type of the key store for this SSL configuration.

Returns:
the argument that was passed to the setKeyStoreType(String) method of this interface or null if setKeyStoreType was not

setKeyStoreType

void setKeyStoreType(java.lang.String keyStoreType)

Sets the type of key store for this SSL configuration.

A key store type can be JKS, JCEK, etc.

setKeyStorePassword(String)

getTrustStore

java.lang.String getTrustStore()

Gets the trust store file path name for this SSL configuration.

Returns:
the absolute path of the argument that was passed to the setTrustStore(String) method of this interface or null if setTrustStore was not

setTrustStore

void setTrustStore(java.lang.String trustStore)

Sets the trust store file path name for this SSL configuration.

A truststore contains certificates for the signers that are trusted in the environment where the truststore is used.

Parameters:
trustStore - the file path name to a trust store
Throws:
java.lang.IllegalArgumentException - if trustStore is null setTrustStoreType(String)

getTrustStorePassword

java.lang.String getTrustStorePassword()

Gets the password of the trust store for this SSL configuration.

Returns:
the argument that was passed to the setTrustStorePassword(String) method of this interface or null if setTrustStorePassword was not

setTrustStorePassword

void setTrustStorePassword(java.lang.String trustStorePassword)

Sets the password of the trust store for this SSL configuration.

setTrustStoreType(String)

getTrustStoreType

java.lang.String getTrustStoreType()

Gets the type of the trust store for this SSL configuration.

Returns:
the argument that was passed to the setTrustStoreType(String) method of this interface or null if setTrustStoreType was not

setTrustStoreType

void setTrustStoreType(java.lang.String trustStoreType)

Sets the type of the trust store for this SSL configuration.

A trust store type can be JKS, JCEK, etc.

setTrustStorePassword(String)

getCertReqSubjectDN

java.lang.String getCertReqSubjectDN()

Gets the required subject DN in the peer certificate for this SSL configuration.

Returns:
the argument that was passed to the setCertReqSubjectDN(String) method of this interface or null if setCertReqSubjectDN was not previously called for this object.

setCertReqSubjectDN

void setCertReqSubjectDN(java.lang.String subjectDN)

Sets the required subject DN in the peer certificate for this SSL configuration.

A connection will be opened only if the peer certficate's subject DN matches this value. Otherwise, the connection will be closed.

Parameters:
subjectDN - the required subject DN in the peer certificate

equals

boolean equals(SSLConfiguration config)

Checks two SSLConfiguration objects for equality.

Parameters:
config - the SSLConfiguration object we are testing for equality with this object.
Returns:
true if both SSLConfiguration objects are equivalent.


com.ibm.websphere.objectgrid.security
Class ObjectGridSecurityException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          com.ibm.websphere.objectgrid.ObjectGridException
              com.ibm.websphere.objectgrid.security.ObjectGridSecurityException

All Implemented Interfaces:
IObjectGridException, java.io.Serializable

Direct Known Subclasses:
CannotGenerateCredentialException, ExpiredCredentialException, InvalidCredentialException

public class ObjectGridSecurityException
extends ObjectGridException

This exception represents a general ObjectGrid security exception.

Since:
WAS XD 6.0, XC10

Constructor Summary
ObjectGridSecurityException()
          Constructs a new ObjectGridSecurityException with null as its detail message.
ObjectGridSecurityException(java.lang.String message)
          Constructs a new ObjectGridSecurityException with the specified detail message.
ObjectGridSecurityException(java.lang.String message, java.lang.Throwable cause)
          Constructs a new ObjectGridSecurityException with the specified detail message and cause.
ObjectGridSecurityException(java.lang.Throwable cause)
          Constructs a new ObjectGridSecurityException with a specified cause.
 
Method Summary
 
Methods inherited from class com.ibm.websphere.objectgrid.ObjectGridException

getCause, initCause
 
Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
 
Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ObjectGridSecurityException

public ObjectGridSecurityException()

Constructs a new ObjectGridSecurityException with null as its detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

ObjectGridSecurityException

public ObjectGridSecurityException(java.lang.String message)

Constructs a new ObjectGridSecurityException with the specified detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

Parameters:
message - the detail message. The detail message is saved for later Throwable.getMessage()

ObjectGridSecurityException

public ObjectGridSecurityException(java.lang.String message,
                                   java.lang.Throwable cause)

Constructs a new ObjectGridSecurityException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this ObjectGridSecurityException's detail message.

Parameters:
message - the detail message (which is saved for later retrieval by the getMessage method).
cause - the cause (which is saved for later retrieval by the getCause method). (Anull value is permitted, and indicates that the cause is nonexistent or Throwable.getMessage()

ObjectGridSecurityException

public ObjectGridSecurityException(java.lang.Throwable cause)

Constructs a new ObjectGridSecurityException with a specified cause. The cause and a detail message of (cause==null ? null : cause.toString()) is used (which typically contains the class and detail message of cause). This constructor is useful for ObjectGridSecurityExceptions that are little more than wrappers for other throwables.

Parameters:
cause - is the exception that caused this exception to be thrown, which is saved for later retrieval by the getCause() method. A null value is permitted and indicates that the cause


com.ibm.websphere.objectgrid.security
Class SecurityConstants

java.lang.Object
  com.ibm.websphere.objectgrid.security.SecurityConstants


public class SecurityConstants
extends java.lang.Object

This class contains the constants used for security configuration.

Since:
WAS XD 6.0, XC10

Field Summary
static int ACCESS_BY_CREATOR_ONLY_COMPLEMENT
          The access by creator only authorization is enabled to complement the ObjectGrid map authorization.
static int ACCESS_BY_CREATOR_ONLY_DISABLED
          The access by creator only authorization is disabled.
static int ACCESS_BY_CREATOR_ONLY_SUPERSEDE
          The access by creator only authorization is enabled to supersede the ObjectGrid map authorization.
static int AUTHORIZATION_MECHANISM_CUSTOM
          Constant representing custom authorization
static int AUTHORIZATION_MECHANISM_JAAS
          Constant representing JAAS authorization
static int CLIENT_CERTIFICATE_AUTHENTICATION_NEVER
          Constant indicating client certificate authentication is not supported.
static int CLIENT_CERTIFICATE_AUTHENTICATION_REQUIRED
          Constant indicating client certificate authentication is required.
static int CLIENT_CERTIFICATE_AUTHENTICATION_SUPPORTED
          Constant indicating client certificate authentication is supported.
static int CREDENTIAL_AUTHENTICATION_NEVER
          Constant indicating credential authentication is not supported.
static int CREDENTIAL_AUTHENTICATION_REQUIRED
          Constant indicating credential authentication is required.
static int CREDENTIAL_AUTHENTICATION_SUPPORTED
          Constant indicating credential authentication is supported.
static java.lang.String NEVER_STRING
          String representation for value Never indicating an option is not supported.
static java.lang.String REQUIRED_STRING
          String representation for value Required indicating an option is required.
static java.lang.String SECURE_TOKEN_MANAGER_CUSTOM_STRING
          String representation for "custom" type of the secure token manager.
static java.lang.String SECURE_TOKEN_MANAGER_DEFAULT_STRING
          String representation for "default" type of the secure token manager.
static java.lang.String SECURE_TOKEN_MANAGER_NONE_STRING
          String representation for "none" type of the secure token manager.
static int SSL_REQUIRED
          Constant indicating SSL transport is required.
static java.lang.String SSL_REQUIRED_STRING
          String representation for value SSL-Required indicating SSL transport type is required.
static int SSL_SUPPORTED
          Constant indicating SSL transport is supported.
static java.lang.String SSL_SUPPORTED_STRING
          String representation for value SSL-Supported indicating SSL transport type is supported.
static java.lang.String SUPPORTED_STRING
          String representation for value Supported indicating an option is supported.
static int TCP_IP
          Constant indicating TCP/IP is the only supported transport.
static java.lang.String TCPIP_STRING
          String representation for value TCP/IP indicating a transport type of TCP/IP is used.
 
Constructor Summary
SecurityConstants()
           
 
Method Summary
 
Methods inherited from class java.lang.Object

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

Field Detail

AUTHORIZATION_MECHANISM_JAAS

public static final int AUTHORIZATION_MECHANISM_JAAS

Constant representing JAAS authorization

AUTHORIZATION_MECHANISM_CUSTOM

public static final int AUTHORIZATION_MECHANISM_CUSTOM

Constant representing custom authorization

TCP_IP

public static final int TCP_IP

Constant indicating TCP/IP is the only supported transport.

If the client's transport type is set to this value, TCP/IP is the only supported transport type. If the server requires SSL, the client won't be able to connect to the server.

Since:

SSL_SUPPORTED

public static final int SSL_SUPPORTED

Constant indicating SSL transport is supported.

If the client's transport type is set to this value, the client supports both TCP/IP and SSL. SSL will be used if both sides side supports SSL. Otherwise, TCP/IP will be used.

Since:
WAS XD 6.0.1
Constant Field Values

SSL_REQUIRED

public static final int SSL_REQUIRED

Constant indicating SSL transport is required.

If the client's transport type is set to this value, SSL is the only supported transport type. If the server requires TCP/IP, the client won't be able to connect to the server.

Since:
WAS XD 6.0.1
Constant Field Values

CREDENTIAL_AUTHENTICATION_NEVER

public static final int CREDENTIAL_AUTHENTICATION_NEVER

Constant indicating credential authentication is not supported.

If the credential authentication type is set to this value, no credential authentication will be enforced. If the server requires credential authentication, the client won't be able to connect to the server.

Since:
WAS XD 6.0.1
Constant Field Values

CREDENTIAL_AUTHENTICATION_SUPPORTED

public static final int CREDENTIAL_AUTHENTICATION_SUPPORTED

Constant indicating credential authentication is supported.

If the credential authentication type is set to this value, credential authentication will be enforced if and only if both client and server support credential authentication.

Since:
WAS XD 6.0.1
Constant Field Values

CREDENTIAL_AUTHENTICATION_REQUIRED

public static final int CREDENTIAL_AUTHENTICATION_REQUIRED

Constant indicating credential authentication is required.

If the credential authentication type is set to this value, credential authentication will be enforced. If the server doesn't support credential authentication, the client won't be able to connect to the server.

Since:
WAS XD 6.0.1
Constant Field Values

CLIENT_CERTIFICATE_AUTHENTICATION_NEVER

public static final int CLIENT_CERTIFICATE_AUTHENTICATION_NEVER

Constant indicating client certificate authentication is not supported.

If the client certificate authentication type is set to this value, no client certificate authentication will be enforced. If the server doesn't support client certificate authentication, the client won't be able to connect to the server.

Since:
WAS XD 6.0.1
Constant Field Values

CLIENT_CERTIFICATE_AUTHENTICATION_SUPPORTED

public static final int CLIENT_CERTIFICATE_AUTHENTICATION_SUPPORTED

Constant indicating client certificate authentication is supported.

If the client certificate authentication type is set to this value, client certificate authentication will be enforced when the following conditions are met:

  • both client and server supports or requires client certificate authentication;
  • the transport protocol to use is SSL;
  • no credential authentication will be done.

Since:
WAS XD 6.0.1
Constant Field Values

CLIENT_CERTIFICATE_AUTHENTICATION_REQUIRED

public static final int CLIENT_CERTIFICATE_AUTHENTICATION_REQUIRED

Constant indicating client certificate authentication is required. If the client certificate authentication type is set to this value, client certificate authentication will be enforced if the following conditions are met:
  • both client and server supports or requires client certificate authentication;
  • the transport protocol to use is SSL;
  • no credential authentication will be done.

If the server doesn't support client certificate authentication and no credential authentication will be done, the client won't be able to connect to the server.

Since:
WAS XD 6.0.1
Constant Field Values

NEVER_STRING

public static final java.lang.String NEVER_STRING

String representation for value Never indicating an option is not supported.

This value is used as a value to configuration settings in a Properties object or property file for client and server security configurations. It is used for the configuration settings "clientCertificateAuthentication" and "credentialAuthentication".

Since:
WAS XD 6.0.1
CREDENTIAL_AUTHENTICATION_NEVER, Constant Field Values

SUPPORTED_STRING

public static final java.lang.String SUPPORTED_STRING

String representation for value Supported indicating an option is supported.

This value is used as a value to configuration settings in a Properties object or property file for client and server security configurations. It is used for the configuration settings "clientCertificateAuthentication" and "credentialAuthentication".

Since:
WAS XD 6.0.1
CREDENTIAL_AUTHENTICATION_SUPPORTED, Constant Field Values

REQUIRED_STRING

public static final java.lang.String REQUIRED_STRING

String representation for value Required indicating an option is required.

This value is used as a value to configuration settings in a Properties object or property file for client and server security configurations. It is used for the configuration settings "clientCertificateAuthentication" and "credentialAuthentication".

Since:
WAS XD 6.0.1
CREDENTIAL_AUTHENTICATION_REQUIRED, Constant Field Values

TCPIP_STRING

public static final java.lang.String TCPIP_STRING

String representation for value TCP/IP indicating a transport type of TCP/IP is used.

This value is used as a value to configuration settings in a Properties object or property file for client and server security configurations. It is used for the configuration setting "transportType".

Since:
WAS XD 6.0.1
Constant Field Values

SSL_SUPPORTED_STRING

public static final java.lang.String SSL_SUPPORTED_STRING

String representation for value SSL-Supported indicating SSL transport type is supported.

This value is used as a value to configuration settings in a Properties object or property file for client and server security configurations. It is used for the configuration setting "transportType".

Since:
WAS XD 6.0.1
Constant Field Values

SSL_REQUIRED_STRING

public static final java.lang.String SSL_REQUIRED_STRING

String representation for value SSL-Required indicating SSL transport type is required.

This value is used as a value to configuration settings in a Properties object or property file for client and server security configurations. It is used for the configuration setting "transportType".

Since:
WAS XD 6.0.1
Constant Field Values

SECURE_TOKEN_MANAGER_NONE_STRING

public static final java.lang.String SECURE_TOKEN_MANAGER_NONE_STRING

String representation for "none" type of the secure token manager.

This value is used in a property file for server security configurations. It is used for the configuration setting "secureTokenManagerType".

Since:
WAS XD 6.0.1

SECURE_TOKEN_MANAGER_DEFAULT_STRING

public static final java.lang.String SECURE_TOKEN_MANAGER_DEFAULT_STRING

String representation for "default" type of the secure token manager.

This value is used in a property file for server security configurations. It is used for the configuration setting "secureTokenManagerType". This value requires users to provide the secure token key store settings.

Since:
WAS XD 6.0.1

SECURE_TOKEN_MANAGER_CUSTOM_STRING

public static final java.lang.String SECURE_TOKEN_MANAGER_CUSTOM_STRING

String representation for "custom" type of the secure token manager.

This value is used in a property file for server security configurations. It is used for the configuration setting "secureTokenManagerType". This value requires users to provide the SecureTokenManager implementation class name using the "customSecureTokenManagerClass" configuration setting.

Since:
WAS XD 6.0.1

ACCESS_BY_CREATOR_ONLY_DISABLED

public static final int ACCESS_BY_CREATOR_ONLY_DISABLED

The access by creator only authorization is disabled.

The access by creator authorization ensures that only the user (represented by the Principals associated with it), who inserts the data entry into the map, can access the data. Here the access means read, update, invalidate, and remove.

Since:
WAS XD 6.1 FIX3

ACCESS_BY_CREATOR_ONLY_COMPLEMENT

public static final int ACCESS_BY_CREATOR_ONLY_COMPLEMENT

The access by creator only authorization is enabled to complement the ObjectGrid map authorization.

The access by creator authorization ensures that only the user (represented by the Principals associated with it), who inserts the data entry into the map, can access the data. Here the access means read, update, invalidate, and remove.

If this constant is used, both map authorization and access by creator only authorization will take effect. Therefore, we can further limit the operations to the data entries. For example, we can restrict the creator from invalidating the data entries.

Since:
WAS XD 6.1 FIX3

ACCESS_BY_CREATOR_ONLY_SUPERSEDE

public static final int ACCESS_BY_CREATOR_ONLY_SUPERSEDE

The access by creator only authorization is enabled to supersede the ObjectGrid map authorization.

The access by creator authorization ensures that only the user (represented by the Principals associated with it), who inserts the data entry into the map, can access the data. Here the access means read, update, invalidate, and remove.

If this constant is used, the access by creator only authorization will supersede the map authorization; no map authorization will be done.

Since:
WAS XD 6.1 FIX3
Constructor Detail

SecurityConstants

public SecurityConstants()


Package com.ibm.websphere.objectgrid.config

This package contains the interfaces and a factory class for creating ObjectGrid configuration objects programatically.

See:
          Description

Interface Summary
BackingMapConfiguration
A BackingMapConfiguration object can be used to override BackingMap settings on the client side.
ConfigProperty
ConfigProperty can be used to attach properties to a Plugin.
ObjectGridConfiguration
An ObjectGridConfiguration object can be used to override ObjectGrid plugins on the client side.
Plugin
This interface represents an ObjectGrid or BackingMap plugin.
PluginType
Every Plugin has a PluginType.
 

Class Summary
ConfigPropertyType
ConfigPropertyType is used to set the type of an attribute on a Plugin.
ObjectGridConfigFactory
This is the configuration factory for ObjectGrid configuration entities.
QueryConfig
This QueryConfig represents a schema configuration for a QueryManager.
QueryMapping
A QueryMapping maps a Java class to a BackingMap and allows a map to be included in a query.
QueryRelationship
A QueryRelationship represents a relationship between two BackingMap value classes.
 

Exception Summary
ObjectGridConfigurationException
Thrown when a problem with the current configuration is found.
 


Package com.ibm.websphere.objectgrid.config Description

This package contains the interfaces and a factory class for creating ObjectGrid configuration objects programatically. The main use of this is by the objectgrid client to override serverside configuration.


Overview

ObjectGridManagerFactory has static methods to create the configuration objects. Using these configuration objects in conjuction with ObjectGridManager methods

to override client configuration, before connecting to the objectgrid server.


com.ibm.websphere.objectgrid.config
Interface BackingMapConfiguration

public interface BackingMapConfiguration

A BackingMapConfiguration object can be used to override BackingMap settings on the client side. The com.ibm.websphere.objectgrid.plugins.Evictor and the com.ibm.websphere.objectgrid.plugins.MapEventListener Plugins can be overridden. Other Evictor related settings can be tweaked.

Use the com.ibm.websphere.objectgrid.config.ObjectGridConfigFactory.createBackingMapConfiguration(String) method to create a BackingMapConfiguration

Since:
WAS XD 6.0.1.2, XC10
MapEventListener, Plugin, ObjectGridConfigFactory

Method Summary
void addPlugin(Plugin plugin)
          Add a Plugin to this BackingMapConfiguration.
java.lang.String getEvictionTriggers()
          Gets the list of eviction triggers for this BackingMapConfiguration.
java.lang.String getName()
          Get the name of this BackingMapConfiguration
int getNumberOfBuckets()
          Gets the number of buckets defined for this BackingMapConfiguration.
java.util.List getPlugins()
          Get the Plugins that have been attached to this BackingMapConfiguration.
int getTimeToLive()
          Gets the "time to live" for each map entry.
TTLType getTtlEvictorType()
          Gets the "time to live" Evictor type for this BackingMapConfiguration.
void setEvictionTriggers(java.lang.String evictionTriggers)
          Sets the eviction triggers for this BackingMapConfiguration.
void setNumberOfBuckets(int numBuckets)
          Sets the number of buckets for this BackingMapConfiguration.
void setPlugins(java.util.List pluginList)
          Set the Plugins for this BackingMapConfiguration.
void setTimeToLive(int seconds)
          Sets "time to live" of each BackingMap entry in seconds.
void setTtlEvictorType(TTLType ttlEvictorType)
          Set the "time to live" Evictor type for this BackingMapConfiguration.
 

Method Detail

getName

java.lang.String getName()

Get the name of this BackingMapConfiguration

Returns:
The name of this BackingMapConfiguration

addPlugin

void addPlugin(Plugin plugin)

Add a Plugin to this BackingMapConfiguration. The Plugins that can be overridden on a client-side BackingMap are com.ibm.websphere.objectgrid.plugins.Evictor and com.ibm.websphere.objectgrid.plugins.MapEventListener.

setPlugins

void setPlugins(java.util.List pluginList)

Set the Plugins for this BackingMapConfiguration. Any Plugins that were previously attached to this BackingMapConfiguration object will be overridden.

getPlugins

java.util.List getPlugins()

Get the Plugins that have been attached to this BackingMapConfiguration.

Returns:
a List of Plugin objects

getNumberOfBuckets

int getNumberOfBuckets()

Gets the number of buckets defined for this BackingMapConfiguration.

Returns:
the number of buckets defined

setNumberOfBuckets

void setNumberOfBuckets(int numBuckets)

Sets the number of buckets for this BackingMapConfiguration. This will be used by the BackingMap.

The BackingMap implementation uses a hash map for its implementation. If there are a lot of entries in the BackingMap then more buckets means better performance because the risk of collisions is lower as the number of buckets grows. More buckets also means more concurrency.

getTimeToLive

int getTimeToLive()

Gets the "time to live" for each map entry. The value is in seconds.

Returns:
the "time to live" in seconds

setTimeToLive

void setTimeToLive(int seconds)

Sets "time to live" of each BackingMap entry in seconds.

If this method is not called, the lifetime of an entry is forever (or until the application explicitly removes or invalidates the entry, or a user defined Evictor evicts the entry).

Parameters:
seconds -

getTtlEvictorType

TTLType getTtlEvictorType()

Gets the "time to live" Evictor type for this BackingMapConfiguration. If setTtlEvictorType was not called, this method will return null and the BackingMap based off this BackingMapConfiguration will use TTLType.NONE

setTtlEvictorType

void setTtlEvictorType(TTLType ttlEvictorType)

Set the "time to live" Evictor type for this BackingMapConfiguration. This is used to determine how expiration time of a BackingMap entry is computed.

If this method is not called, TTLType.NONE is used to indicate the map entry has no expiration time (e.g. is allowed to live until explicitly removed or invalidated by the application, or evicted by a user defined Evictor).

getEvictionTriggers

java.lang.String getEvictionTriggers()

Gets the list of eviction triggers for this BackingMapConfiguration.

See BackingMap for a list of valid eviction triggers.

Returns:
a semicolon separated list of eviction triggers or null if setEvictionTriggers(String) was not called
Since:
WAS XD 6.1.0.3

setEvictionTriggers

void setEvictionTriggers(java.lang.String evictionTriggers)

Sets the eviction triggers for this BackingMapConfiguration. All evictors will use the eviction supplied triggers.

See BackingMap for a list of valid eviction triggers.

Parameters:
evictionTriggers - a semicolon separated list of eviction triggers
Since:
WAS XD 6.1.0.3


com.ibm.websphere.objectgrid.config
Interface ConfigProperty

All Superinterfaces:
java.io.Serializable

public interface ConfigProperty
extends java.io.Serializable

ConfigProperty can be used to attach properties to a Plugin. A ConfigProperty has the following attributes:

  • name: the property name
  • value: the property value
  • configPropertyType: the configuration property type

This ConfigProperty can be used to set the properties of a plugin. The name of the property should follow JaveBean convention. That is, for every property, there should be a corresponding set method in the plugin class.

Users can use com.ibm.websphere.objectgrid.config.ObjectGridConfigFactory.createConfigProperty(ConfigPropertyType, String, String) to create a ConfigProperty object.

ConfigProperty evictorNameProp = ObjectGridConfigFactory.createConfigProperty(ConfigProperty.STRING_JAVA_LANG, "evictorName", "evictor1"); This creates a property "evictorName" with value "evictor1", and the type is java.lang.String. Use the com.ibm.websphere.objectgrid.config.Plugin#addConfigProperty(ConfigProperty) method to attach a ConfigProperty to a Plugin. When the Plugin is created, each ConfigProperty will have its corresponding set method called.

Continuing with the example above, attach the ConfigProperty to an Evictor Plugin. evictorPlugin.addConfigProperty(evictorNameProp);

When this Evictor Plugin is created, the setEvictorName(String) method will be called with the value "evictor1".

Since:
WAS XD 6.0.1.2, XC10

Method Summary
ConfigPropertyType getConfigPropertyType()
          Get the ConfigPropertyType of this object.
java.lang.String getName()
          Get the name of this object.
java.lang.String getValue()
          Get the value that is assigned to this ConfigProperty.
void setConfigPropertyType(ConfigPropertyType configPropType)
          Set the ConfigPropertyType for this object.
void setName(java.lang.String name)
          Set the name of this object.
void setValue(java.lang.String value)
          Set the value of this ConfigProperty.
 

Method Detail

setConfigPropertyType

void setConfigPropertyType(ConfigPropertyType configPropType)

Set the ConfigPropertyType for this object. The Java primitives, their java.lang counterparts, and java.lang.String are the supported ConfigPropertyTypes.

ConfigPropertyType.INT_PRIM, ConfigPropertyType.BOOLEAN_JAVA_LANG, ConfigPropertyType.BOOLEAN_PRIM, ConfigPropertyType.CHARACTER_JAVA_LANG, ConfigPropertyType.CHAR_PRIM, ConfigPropertyType.BYTE_JAVA_LANG, ConfigPropertyType.BYTE_PRIM, ConfigPropertyType.SHORT_JAVA_LANG, ConfigPropertyType.SHORT_PRIM, ConfigPropertyType.LONG_JAVA_LANG, ConfigPropertyType.LONG_PRIM, ConfigPropertyType.FLOAT_JAVA_LANG, ConfigPropertyType.FLOAT_PRIM, ConfigPropertyType.DOUBLE_JAVA_LANG, ConfigPropertyType.DOUBLE_PRIM, ConfigPropertyType.STRING_JAVA_LANG

getConfigPropertyType

ConfigPropertyType getConfigPropertyType()

Get the ConfigPropertyType of this object.

Returns:
the ConfigPropertyType for this object

setValue

void setValue(java.lang.String value)

Set the value of this ConfigProperty. This String value will be converted to the proper type, based on ConfigPropertyType assigned to this ConfigProperty

Parameters:
value - - will be converted to type and passed to the setter on the plugin

getValue

java.lang.String getValue()

Get the value that is assigned to this ConfigProperty. This is the value that will be passed to the set method on the plugin.

Returns:
Returns the value.

setName

void setName(java.lang.String name)

Set the name of this object. The Plugin that this ConfigProperty is attached to should have a setter that corresponds to this name. For example, if "size" is passed in as the name, then the Plugin must have a "setSize" method.

Parameters:
name - - name of the property

getName

java.lang.String getName()

Get the name of this object. The name must have a corresponding set method on the Plugin.

Returns:
Returns the name.


com.ibm.websphere.objectgrid.config
Class ConfigPropertyType

java.lang.Object
  com.ibm.websphere.objectgrid.config.ConfigPropertyType

All Implemented Interfaces:
java.io.Serializable

public final class ConfigPropertyType
extends java.lang.Object
implements java.io.Serializable

ConfigPropertyType is used to set the type of an attribute on a Plugin. The Java primitives, their java.lang counterparts, and java.lang.String are the supported types.

Since:
WAS XD 6.0.1.2, XC10
Plugin.setPluginType(PluginType), Serialized Form

Field Summary
static ConfigPropertyType BOOLEAN_JAVA_LANG
          ConfigPropertyType.BOOLEAN_JAVA_LANG can be used to set a property of type java.lang.Boolean on a plugin.
static ConfigPropertyType BOOLEAN_PRIM
          ConfigPropertyType.BOOLEAN_PRIM can be used to set a property of type boolean on a plugin.
static ConfigPropertyType BYTE_JAVA_LANG
          ConfigPropertyType.BYTE_JAVA_LANG can be used to set a property of type java.lang.Byte on a plugin.
static ConfigPropertyType BYTE_PRIM
          ConfigPropertyType.BYTE_PRIM can be used to set a property of type byte on a plugin.
static ConfigPropertyType CHAR_PRIM
          ConfigPropertyType.CHAR_PRIM can be used to set a property of type char on a plugin.
static ConfigPropertyType CHARACTER_JAVA_LANG
          ConfigPropertyType.CHARACTER_JAVA_LANG can be used to set a property of type java.lang.Character on a plugin.
static ConfigPropertyType DOUBLE_JAVA_LANG
          ConfigPropertyType.DOUBLE_JAVA_LANG can be used to set a property of type java.lang.Double on a plugin.
static ConfigPropertyType DOUBLE_PRIM
          ConfigPropertyType.DOUBLE_PRIM can be used to set a property of type double on a plugin.
static ConfigPropertyType FLOAT_JAVA_LANG
          ConfigPropertyType.FLOAT_JAVA_LANG can be used to set a property of type java.lang.Float on a plugin.
static ConfigPropertyType FLOAT_PRIM
          ConfigPropertyType.FLOAT_PRIM can be used to set a property of type float on a plugin.
static ConfigPropertyType INT_PRIM
          ConfigPropertyType.INT_PRIM can be used to set a property of type int on a plugin.
static ConfigPropertyType INTEGER_JAVA_LANG
          ConfigPropertyType.INTEGER_JAVA_LANG can be used to set a property of type java.lang.Integer on a plugin.
static ConfigPropertyType LONG_JAVA_LANG
          ConfigPropertyType.LONG_JAVA_LANG can be used to set a property of type java.lang.Long on a plugin.
static ConfigPropertyType LONG_PRIM
          ConfigPropertyType.LONG_PRIM can be used to set a property of type long on a plugin.
static ConfigPropertyType SHORT_JAVA_LANG
          ConfigPropertyType.SHORT_JAVA_LANG can be used to set a property of type java.lang.Short on a plugin.
static ConfigPropertyType SHORT_PRIM
          ConfigPropertyType.SHORT_PRIM can be used to set a property of type short on a plugin.
static ConfigPropertyType STRING_JAVA_LANG
          ConfigPropertyType.STRING_JAVA_LANG can be used to set a property of type java.lang.String on a plugin.
 
Method Summary
boolean equals(java.lang.Object o)
           
int hashCode()
           
java.lang.String toString()
           
 
Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

INTEGER_JAVA_LANG

public static final ConfigPropertyType INTEGER_JAVA_LANG

ConfigPropertyType.INTEGER_JAVA_LANG can be used to set a property of type java.lang.Integer on a plugin.

INT_PRIM

public static final ConfigPropertyType INT_PRIM

ConfigPropertyType.INT_PRIM can be used to set a property of type int on a plugin.

BOOLEAN_JAVA_LANG

public static final ConfigPropertyType BOOLEAN_JAVA_LANG

ConfigPropertyType.BOOLEAN_JAVA_LANG can be used to set a property of type java.lang.Boolean on a plugin.

BOOLEAN_PRIM

public static final ConfigPropertyType BOOLEAN_PRIM

ConfigPropertyType.BOOLEAN_PRIM can be used to set a property of type boolean on a plugin.

CHARACTER_JAVA_LANG

public static final ConfigPropertyType CHARACTER_JAVA_LANG

ConfigPropertyType.CHARACTER_JAVA_LANG can be used to set a property of type java.lang.Character on a plugin.

CHAR_PRIM

public static final ConfigPropertyType CHAR_PRIM

ConfigPropertyType.CHAR_PRIM can be used to set a property of type char on a plugin.

BYTE_JAVA_LANG

public static final ConfigPropertyType BYTE_JAVA_LANG

ConfigPropertyType.BYTE_JAVA_LANG can be used to set a property of type java.lang.Byte on a plugin.

BYTE_PRIM

public static final ConfigPropertyType BYTE_PRIM

ConfigPropertyType.BYTE_PRIM can be used to set a property of type byte on a plugin.

SHORT_JAVA_LANG

public static final ConfigPropertyType SHORT_JAVA_LANG

ConfigPropertyType.SHORT_JAVA_LANG can be used to set a property of type java.lang.Short on a plugin.

SHORT_PRIM

public static final ConfigPropertyType SHORT_PRIM

ConfigPropertyType.SHORT_PRIM can be used to set a property of type short on a plugin.

LONG_JAVA_LANG

public static final ConfigPropertyType LONG_JAVA_LANG

ConfigPropertyType.LONG_JAVA_LANG can be used to set a property of type java.lang.Long on a plugin.

LONG_PRIM

public static final ConfigPropertyType LONG_PRIM

ConfigPropertyType.LONG_PRIM can be used to set a property of type long on a plugin.

FLOAT_JAVA_LANG

public static final ConfigPropertyType FLOAT_JAVA_LANG

ConfigPropertyType.FLOAT_JAVA_LANG can be used to set a property of type java.lang.Float on a plugin.

FLOAT_PRIM

public static final ConfigPropertyType FLOAT_PRIM

ConfigPropertyType.FLOAT_PRIM can be used to set a property of type float on a plugin.

DOUBLE_JAVA_LANG

public static final ConfigPropertyType DOUBLE_JAVA_LANG

ConfigPropertyType.DOUBLE_JAVA_LANG can be used to set a property of type java.lang.Double on a plugin.

DOUBLE_PRIM

public static final ConfigPropertyType DOUBLE_PRIM

ConfigPropertyType.DOUBLE_PRIM can be used to set a property of type double on a plugin.

STRING_JAVA_LANG

public static final ConfigPropertyType STRING_JAVA_LANG

ConfigPropertyType.STRING_JAVA_LANG can be used to set a property of type java.lang.String on a plugin.

Method Detail

equals

public boolean equals(java.lang.Object o)

Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:
hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:
toString in class java.lang.Object


com.ibm.websphere.objectgrid.config
Class ObjectGridConfigFactory

java.lang.Object
  com.ibm.websphere.objectgrid.config.ObjectGridConfigFactory


public final class ObjectGridConfigFactory
extends java.lang.Object

This is the configuration factory for ObjectGrid configuration entities. Users are expected to use static methods of this factory to create ObjectGrid configuration objects.

Here is a list of static methods used to create configuration objects:

  • createObjectGridConfiguration(String): create an ObjectGridConfiguration object
  • createBackingMapConfiguration(String): create a BackingMapConfiguration object by passing a backing map name
  • createConfigProperty(ConfigPropertyType, String, String): create a ConfigProperty object
  • createPlugin(PluginType, String): create a Plugin object

Below is an example of creating an ObjectGrid configuration. A Plugin is added to the ObjectGridConfiguration object: com.ibm.websphere.objectgrid.plugins.ObjectGridEventListener plugin.

A BackingMapConfiguration called "myBackingMap" is then created and added to the ObjectGridConfiguration. This BackingMapConfiguration also has an Evictor Plugin configured.

Once the ObjectGridConfiguration object has been created, it can be used to call either of these methods

  • com.ibm.websphere.objectgrid.ObjectGridManager.putOverrideObjectGridConfigurations(String, List)
  • com.ibm.websphere.objectgrid.ObjectGridManager.setOverrideObjectGridConfigurations(Map)

to set configuration objects, prior to connecting. 

 // Create an ObjectGridConfiguration object
 ObjectGridConfiguration ogConfig = ObjectGridConfigFactory.createObjectGridConfiguration(ogName);

 // create ObjectGridEventListener plugin
 Plugin eventListener = ObjectGridConfigFactory.createPlugin(PluginType.OBJECTGRID_EVENT_LISTENER,"com.ibm.test.MyOgEventListener");

 // Add plugin to ObjectGridConfiguration object
 ogConfig.addPlugin(eventListener);

 // Create a BackingMapConfiguration object
 BackingMapConfiguration bmConfig = ObjectGridConfigFactory.createBackingMapConfiguration("mybackingMap");

 // Add BackingMapConfiguration object to ObjectGridConfiguration object
 ogConfig.addBackingMapConfiguration(bmConfig);

 // Set the number of buckets to 1000
 bmConfig.setNumberOfBuckets(1000);

 // Create a Evictor plugin for this backing map.
 Plugin evictor = ObjectGridConfigFactory.createPlugin(
 BackingMapConfiguration.PLUGIN_EVICTOR,
 com.acme.myEvictorImpl.class.getName());

 // add Evictor Plugin to the BackingMapConfiguration
 bmConfig.addPlugin(evictor);

 // Create a ConfigProperty for the Evictor plugin
 ConfigProperty sizeProperty = ObjectGridConfigFactory.createConfigProperty(
   ConfigPropertyType.INT_PRIM, "size", "153");

 // Add the ConfigProperty to the Evictor plugin
 evictor.setConfigProperty(sizeProperty);

Since:
WAS XD 6.0.1.2, XC10
BackingMapConfiguration, Plugin, ConfigProperty

Constructor Summary
ObjectGridConfigFactory()
           
 
Method Summary
static BackingMapConfiguration createBackingMapConfiguration(java.lang.String backingMapConfigName)
          Create a BackingMapConfiguration object
static ConfigProperty createConfigProperty(ConfigPropertyType configPropType, java.lang.String name, java.lang.String value)
          Create a ConfigPropety object for use on a Plugin.
static ObjectGridConfiguration createObjectGridConfiguration(java.lang.String objectGridConfigName)
          Create an ObjectGridConfiguration object.
static Plugin createOSGiServicePlugin(PluginType pluginType, java.lang.String osgiServiceName)
          Create an OSGi Service Plugin for a BackingMapConfiguration or an ObjectGridConfiguration
static Plugin createPlugin(PluginType pluginType, java.lang.String className)
          Create a Plugin for a BackingMapConfiguration or an ObjectGridConfiguration
 
Methods inherited from class java.lang.Object

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

Constructor Detail

ObjectGridConfigFactory

public ObjectGridConfigFactory()

Method Detail

createPlugin

public static Plugin createPlugin(PluginType pluginType,
                                  java.lang.String className)

Create a Plugin for a BackingMapConfiguration or an ObjectGridConfiguration

Parameters:
pluginType - the PluginType.
className - of the Plugin implementation class to instantiate PluginType.TRANSACTION_CALLBACK, PluginType.COLLISION_ARBITER, PluginType.EVICTOR, PluginType.MAP_EVENT_LISTENER, PluginType.OBJECTGRID_LIFECYCLE_LISTENER, PluginType.MAP_LIFECYCLE_LISTENER

createObjectGridConfiguration

public static ObjectGridConfiguration createObjectGridConfiguration(java.lang.String objectGridConfigName)

Create an ObjectGridConfiguration object.

Parameters:
objectGridConfigName - the name that will be assigned to this ObjectGridConfiguration object
Returns:
the ObjectGridConfiguration object

createBackingMapConfiguration

public static BackingMapConfiguration createBackingMapConfiguration(java.lang.String backingMapConfigName)

Create a BackingMapConfiguration object

Parameters:
backingMapConfigName - the name to assign to this BackingMapConfiguration
Returns:
the BackingMapConfiguration object

createConfigProperty

public static ConfigProperty createConfigProperty(ConfigPropertyType configPropType,
                                                  java.lang.String name,
                                                  java.lang.String value)

Create a ConfigPropety object for use on a Plugin.

The Plugin should have a set method that corresponds to the name of this ConfigProperty. The method must accept a parameter of the ConfigPropertyType specified on this ConfigProperty. For example, if the name of this ConfigProperty is set to "size", and the type is ConfigPropertyType.INT_PRIM, then the Plugin must have the method setSize(int). The value of the ConfigProperty will be passed to the setter of the Plugin when an ObjectGrid is created based on this configuration.

Parameters:
configPropType - ConfigPropertyType of the ConfigProperty. Part of the set method's signature, the type of parameter the set method requires. Valid
name - of the ConfigProperty. It must correspond to the name of a set method on the Plugin.
value - of the ConfigProperty. This value will be passed to the set method on the Plugin. ConfigPropertyType.BOOLEAN_JAVA_LANG, ConfigPropertyType.BOOLEAN_PRIM, ConfigPropertyType.BYTE_JAVA_LANG, ConfigPropertyType.BYTE_PRIM, ConfigPropertyType.CHARACTER_JAVA_LANG, ConfigPropertyType.CHAR_PRIM, ConfigPropertyType.DOUBLE_JAVA_LANG, ConfigPropertyType.DOUBLE_PRIM, ConfigPropertyType.FLOAT_JAVA_LANG, ConfigPropertyType.FLOAT_PRIM, ConfigPropertyType.INTEGER_JAVA_LANG, ConfigPropertyType.INT_PRIM, ConfigPropertyType.LONG_JAVA_LANG, ConfigPropertyType.LONG_PRIM, ConfigPropertyType.SHORT_JAVA_LANG

createOSGiServicePlugin

public static Plugin createOSGiServicePlugin(PluginType pluginType,
                                             java.lang.String osgiServiceName)

Create an OSGi Service Plugin for a BackingMapConfiguration or an ObjectGridConfiguration

Parameters:
pluginType - the PluginType.
osgiServiceName - the OSGi service name
Returns:
a Plugin instance
Since:
7.1.1
PluginType.TRANSACTION_CALLBACK, PluginType.COLLISION_ARBITER, PluginType.EVICTOR, PluginType.MAP_EVENT_LISTENER, PluginType.OBJECTGRID_LIFECYCLE_LISTENER, PluginType.MAP_LIFECYCLE_LISTENER


com.ibm.websphere.objectgrid.config
Interface ObjectGridConfiguration

public interface ObjectGridConfiguration

An ObjectGridConfiguration object can be used to override ObjectGrid plugins on the client side. The com.ibm.websphere.objectgrid.plugins.ObjectGridEventListener and the com.ibm.websphere.objectgrid.plugins.TransactionCallback Plugins can be overridden.

Since:
WAS XD 6.0.1.2, XC10
http://publib.boulder.ibm.com/infocenter/wdpxc/v2http://pic.dhe.ibm.com/infocenter/wxsinfo/v8r6/topic/com.ibm.websphere.extremescale.javadoc.doc/topics/com/ibm/websphere/objectgrid/plugins/TransactionCallback.html http://publib.boulder.ibm.com/infocenter/wdpxc/v2http://pic.dhe.ibm.com/infocenter/wxsinfo/v8r6/topic/com.ibm.websphere.extremescale.javadoc.doc/topics/com/ibm/websphere/objectgrid/plugins/TransactionCallback.html" >TransactionCallback TransactionCallback

Method Summary
void addBackingMapConfiguration(BackingMapConfiguration backingMapConfiguration)
          Add a BackingMapConfiguration to this ObjectGridConfiguration.
void addPlugin(Plugin plugin)
          Add a Plugin to this ObjectGridConfiguration.
java.util.List getBackingMapConfigurations()
          Get the List of BackingMapConfiguration objects that are attached to this ObjectGridConfiguration object
java.lang.String getName()
          Get the name of this ObjectGridConfiguration
java.util.List getPlugins()
          Get the Plugins that have been attached to this ObjectGridConfiguration.
int getTxIsolation()
          Retrieves the default transaction isolation level.
int getTxTimeout()
          Gets the transaction timeout.
void setBackingMapConfigurations(java.util.List backingMapConfigList)
          Set the BackingMapConfiguration objects for this ObjectGridConfiguration.
void setPlugins(java.util.List pluginList)
          Set the Plugins for this ObjectGridConfiguration.
void setTxIsolation(int level)
          Sets the default transaction isolation level for all sessions created by the ObjectGrid.
void setTxTimeout(int seconds)
          Sets the transaction timeout
 

Method Detail

getName

java.lang.String getName()

Get the name of this ObjectGridConfiguration

Returns:
the name of this ObjectGridConfiguration

addBackingMapConfiguration

void addBackingMapConfiguration(BackingMapConfiguration backingMapConfiguration)

Add a BackingMapConfiguration to this ObjectGridConfiguration.

Parameters:
backingMapConfiguration -

setBackingMapConfigurations

void setBackingMapConfigurations(java.util.List backingMapConfigList)

Set the BackingMapConfiguration objects for this ObjectGridConfiguration. Any BackingMapConfiguration objects that were previously attached to this ObjectGridConfiguration object will be overridden.

getBackingMapConfigurations

java.util.List getBackingMapConfigurations()

Get the List of BackingMapConfiguration objects that are attached to this ObjectGridConfiguration object

addPlugin

void addPlugin(Plugin plugin)

Add a Plugin to this ObjectGridConfiguration. The Plugins that can be overridden on a client-side ObjectGrid are com.ibm.websphere.objectgrid.plugins.ObjectGridEventListener and com.ibm.websphere.objectgrid.plugins.TransactionCallback.

Plugin

setPlugins

void setPlugins(java.util.List pluginList)

Set the Plugins for this ObjectGridConfiguration. Any Plugins that were previously attached to this ObjectGridConfiguration object will be overridden.

Plugin

getPlugins

java.util.List getPlugins()

Get the Plugins that have been attached to this ObjectGridConfiguration.

setTxTimeout

void setTxTimeout(int seconds)

Sets the transaction timeout

Parameters:
seconds -
Since:
7.1.0.3

getTxTimeout

int getTxTimeout()

Gets the transaction timeout. The value is in seconds.

Returns:
the transaction timeout in seconds
Since:
7.1.0.3

setTxIsolation

void setTxIsolation(int level)

Sets the default transaction isolation level for all sessions created by the ObjectGrid. The constants defined in the Session interface are the possible transaction isolation levels. The default is Session.TRANSACTION_REPEAtable_READ.

Parameters:
level - one of the following Session constants: Session.TRANSACTION_READ_UNCOMMITTED, Session.TRANSACTION_READ_COMMITTED or Session.TRANSACTION_REPEAtable_READ or 0 if the TransactionIsolation should not be set.
Since:
7.1.1

getTxIsolation

int getTxIsolation()

Retrieves the default transaction isolation level.

Returns:
the current transaction isolation level.
Since:
7.1.1


com.ibm.websphere.objectgrid.config
Class ObjectGridConfigurationException

java.lang.Object
  ava.lang.Throwable
      ava.lang.Exception
          com.ibm.websphere.objectgrid.ObjectGridException
              com.ibm.websphere.objectgrid.config.ObjectGridConfigurationException

All Implemented Interfaces:
IObjectGridException, java.io.Serializable

public class ObjectGridConfigurationException
extends ObjectGridException

Thrown when a problem with the current configuration is found. This exception may be thrown when the configuration specified in the deployment policy, ObjectGrid descriptor or security descriptor is incorrect.

Since:
7.0, XC10

Constructor Summary
ObjectGridConfigurationException()
          Constructs a new ObjectGridConfigurationException with null as its detail message.
ObjectGridConfigurationException(java.lang.String message)
          Constructs a new ObjectGridConfigurationException with the specified detail message.
ObjectGridConfigurationException(java.lang.String message, java.lang.Throwable cause)
          Constructs a new ObjectGridConfigurationException with the specified detail message and cause.
ObjectGridConfigurationException(java.lang.Throwable cause)
          Constructs a new ObjectGridConfigurationException with a specified cause.
 
Method Summary
 
Methods inherited from class com.ibm.websphere.objectgrid.ObjectGridException

getCause, initCause
 
Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
 
Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ObjectGridConfigurationException

public ObjectGridConfigurationException()

Constructs a new ObjectGridConfigurationException with null as its detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

ObjectGridConfigurationException

public ObjectGridConfigurationException(java.lang.String message)

Constructs a new ObjectGridConfigurationException with the specified detail message. The cause is not initialized, and may subsequently be initialized by a call to the initCause method.

Parameters:
message - the detail message. The detail message is saved for later Throwable.getMessage()

ObjectGridConfigurationException

public ObjectGridConfigurationException(java.lang.Throwable cause)

Constructs a new ObjectGridConfigurationException with a specified cause. The cause and a detail message of (cause==null ? null : cause.toString()) is used (which typically contains the class and detail message of cause). This constructor is useful for ObjectGridConfigurationException that are little more than wrappers for other throwables.

Parameters:
cause - is the exception that caused this exception to be thrown, which is saved for later retrieval by the getCause() method. A null value is permitted and indicates that the cause

ObjectGridConfigurationException

public ObjectGridConfigurationException(java.lang.String message,
                                        java.lang.Throwable cause)

Constructs a new ObjectGridConfigurationException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this ObjectGridConfigurationException's detail message.

Parameters:
message - the detail message (which is saved for later retrieval by the getMessage method).
cause - the cause (which is saved for later retrieval by the getCause method). (Anull value is permitted, and indicates that the cause is nonexistent or Throwable.getMessage()


com.ibm.websphere.objectgrid.config
Interface Plugin

All Superinterfaces:
java.io.Serializable

public interface Plugin
extends java.io.Serializable

This interface represents an ObjectGrid or BackingMap plugin. An ObjectGridConfiguration object supports the following Plugins:

  • PluginType#OBJECTGRID_EVENT_LISTENER
  • PluginType#TRANSACTION_CALLBACK

A BackingMapConfiguration object supports the following Plugins:

  • PluginType#EVICTOR
  • PluginType#MAP_EVENT_LISTENER

A Plugin object has following attributes:

  • pluginType: the support PluginTypes are listed above
  • className: the plugin implementation class name. This class name will be used to construct the class object. A default constructor must be implemented.
  • configProperties: the JavaBean properties for this plugin implementation object.

A plugin object can be created by using ObjectGridConfigFactory.createPlugin(PluginType, String) method. Please refer to ObjectGridConfigFactory for detailed example.

Since:
WAS XD 6.0.1.2, XC10

Method Summary
void addConfigProperty(ConfigProperty configProp)
          Add a ConfigProperty to this object.
java.lang.String getClassName()
          Get the String representation of the class name of this Plugin
java.util.List getConfigProperties()
          Get the ConfigProperty objects that have been set on this object.
java.lang.String getOSGiService()
          Get the OSGi service name configured for this Plugin.
PluginType getPluginType()
          Get the PluginType for this Plugin.
void setClassName(java.lang.String className)
          The class name that is set must be an implementor of the PluginTypeImpl for this Plugin.
void setConfigProperties(java.util.List configPropList)
          Set the ConfigProperties for this object
void setOSGiService(java.lang.String osgiService)
          Set the OSGi service name configured for this Plugin.
void setPluginType(PluginType pluginType)
          Set the PluginType for this Plugin.
 

Method Detail

addConfigProperty

void addConfigProperty(ConfigProperty configProp)

Add a ConfigProperty to this object.

Parameters:
configProp - - ConfigProperty to add to this object

setConfigProperties

void setConfigProperties(java.util.List configPropList)

Set the ConfigProperties for this object

Parameters:
configPropList -

getConfigProperties

java.util.List getConfigProperties()

Get the ConfigProperty objects that have been set on this object.

getPluginType

PluginType getPluginType()

Get the PluginType for this Plugin.

Returns:
the PluginType for this Plugin

setPluginType

void setPluginType(PluginType pluginType)

Set the PluginType for this Plugin.

The ObjectGridConfiguration plugins include

  • PluginType.TRANSACTION_CALLBACK
  • PluginType.OBJECTGRID_EVENT_LISTENER

The BackingMapConfiguration plugins include

  • PluginType.EVICTOR
  • PluginType.MAP_EVENT_LISTENER

Parameters:
pluginType -

getClassName

java.lang.String getClassName()

Get the String representation of the class name of this Plugin

Returns:
the String representation of the class name

setClassName

void setClassName(java.lang.String className)

The class name that is set must be an implementor of the PluginTypeImpl for this Plugin. For example, if the type of this Plugin is PluginType.EVICTOR, then the className must be an implementor of the com.ibm.websphere.objectgrid.plugins.Evictor interface.

Parameters:
className - - the class name of the Class that implements the PluginType

getOSGiService

java.lang.String getOSGiService()

Get the OSGi service name configured for this Plugin. If an OSGi service name is configured for this Plugin, the className configured for this Plugin is ignored.

Returns:
the OSGi service name configured for this Plugin.
Since:
7.1.1

setOSGiService

void setOSGiService(java.lang.String osgiService)

Set the OSGi service name configured for this Plugin. If an OSGi service name is configured for this Plugin, the className configured for this Plugin is ignored.

Parameters:
osgiService - the OSGi service name configured for this Plugin.
Since:
7.1.1


com.ibm.websphere.objectgrid.config
Interface PluginType

All Superinterfaces:
java.io.Serializable

public interface PluginType
extends java.io.Serializable

Every Plugin has a PluginType. The PluginType is specified during Plugin creation.

ObjectGridConfiguration objects support the following PluginTypes for overriding client-side ObjectGrid plugins:

  • PluginType.TRANSACTION_CALLBACK
  • PluginType.OBJECTGRID_EVENT_LISTENER
  • PluginType.COLLISION_ARBITER

BackingMapConfiguration objects support the following PluginTypes for overriding client-side BackingMap plugins:

  • PluginType.EVICTOR
  • PluginType.MAP_EVENT_LISTENER

Since:
WAS XD 6.0.1.2, XC10

Field Summary
static PluginType COLLISION_ARBITER
          PluginType.COLLISION_ARBITER can be used to attach a CollisionArbiter plugin to an ObjectGrid.
static PluginType EVICTOR
          PluginType.EVICTOR can be used to attach an Evictor to a BackingMap.
static PluginType MAP_EVENT_LISTENER
          PluginType.MAP_EVENT_LISTENER can be used to attach a MapEventListener to a BackingMap.
static PluginType MAP_LIFECYCLE_LISTENER
          PluginType.MAP_LIFECYCLE_LISTENER can be used to attach a BackingMapLifecycleListener plugin to an BackingMap
static com.ibm.ws.objectgrid.config.PluginTypeImpl MAP_SERIALIZER_PLUGIN
          PluginType.MAP_SERIALIZER_PLUGIN can be used to attach a MapSerializerPlugin to a BackingMap to serialize keys.
static PluginType OBJECTGRID_EVENT_LISTENER
          PluginType.OBJECTGRID_EVENT_LISTENER can be used to attach an ObjectGridEventListener plugin to an ObjectGrid
static PluginType OBJECTGRID_LIFECYCLE_LISTENER
          PluginType.OBJECTGRID_LIFECYCLE_LISTENER can be used to attach an ObjectGridLifecycleListener plugin to an ObjectGrid
static PluginType TRANSACTION_CALLBACK
          PluginType.TRANSACTION_CALLBACK can be used to attach a TransactionCallback plugin to an ObjectGrid.
 

Field Detail

OBJECTGRID_EVENT_LISTENER

static final PluginType OBJECTGRID_EVENT_LISTENER

PluginType.OBJECTGRID_EVENT_LISTENER can be used to attach an ObjectGridEventListener plugin to an ObjectGrid

TRANSACTION_CALLBACK

static final PluginType TRANSACTION_CALLBACK

PluginType.TRANSACTION_CALLBACK can be used to attach a TransactionCallback plugin to an ObjectGrid.

COLLISION_ARBITER

static final PluginType COLLISION_ARBITER

PluginType.COLLISION_ARBITER can be used to attach a CollisionArbiter plugin to an ObjectGrid.

OBJECTGRID_LIFECYCLE_LISTENER

static final PluginType OBJECTGRID_LIFECYCLE_LISTENER

PluginType.OBJECTGRID_LIFECYCLE_LISTENER can be used to attach an ObjectGridLifecycleListener plugin to an ObjectGrid

Since:
7.1.1

EVICTOR

static final PluginType EVICTOR

PluginType.EVICTOR can be used to attach an Evictor to a BackingMap.

MAP_EVENT_LISTENER

static final PluginType MAP_EVENT_LISTENER

PluginType.MAP_EVENT_LISTENER can be used to attach a MapEventListener to a BackingMap.

MAP_SERIALIZER_PLUGIN

static final com.ibm.ws.objectgrid.config.PluginTypeImpl MAP_SERIALIZER_PLUGIN

PluginType.MAP_SERIALIZER_PLUGIN can be used to attach a MapSerializerPlugin to a BackingMap to serialize keys.

Since:
7.1.1

MAP_LIFECYCLE_LISTENER

static final PluginType MAP_LIFECYCLE_LISTENER

PluginType.MAP_LIFECYCLE_LISTENER can be used to attach a BackingMapLifecycleListener plugin to an BackingMap

Since:
7.1.1


com.ibm.websphere.objectgrid.config
Class QueryConfig

java.lang.Object
  com.ibm.websphere.objectgrid.config.QueryConfig

All Implemented Interfaces:
java.io.Serializable

public class QueryConfig
extends java.lang.Object
implements java.io.Serializable

This QueryConfig represents a schema configuration for a QueryManager. A QueryConfig object contains a set of QueryMapping objects and a set of QueryRelationship objects.

Users use addQuerySchema method to add a QueryMapping object and use addRelationship method to add a QueryRelationship object into this QueryConfig object.

Since:
WAS XD 6.1, XC10
QueryMapping, QueryRelationship, Serialized Form

Constructor Summary
QueryConfig()
          Default constructor.
 
Method Summary
void addQueryMapping(QueryMapping mapping)
          Add a QueryMapping to this QueryConfig
void addQueryRelationship(QueryRelationship relation)
          Add a QueryRelationship to this QueryConfig
QueryMapping[] getQueryMappings()
          Retrieve all added QueryMappings
QueryRelationship[] getQueryRelationships()
          Retrieve all added QueryRelationships
 
Methods inherited from class java.lang.Object

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

Constructor Detail

QueryConfig

public QueryConfig()

Default constructor.

Method Detail

addQueryMapping

public void addQueryMapping(QueryMapping mapping)

Add a QueryMapping to this QueryConfig

Parameters:
mapping - the QueryMapping to add.

addQueryRelationship

public void addQueryRelationship(QueryRelationship relation)

Add a QueryRelationship to this QueryConfig

Parameters:
relation - the QueryRelationship to add.

getQueryMappings

public QueryMapping[] getQueryMappings()

Retrieve all added QueryMappings

Returns:
array of QueryMapping

getQueryRelationships

public QueryRelationship[] getQueryRelationships()

Retrieve all added QueryRelationships

Returns:
array of QueryRelationship


com.ibm.websphere.objectgrid.config
Class QueryMapping

java.lang.Object
  com.ibm.websphere.objectgrid.config.QueryMapping

All Implemented Interfaces:
java.io.Serializable

public class QueryMapping
extends java.lang.Object
implements java.io.Serializable

A QueryMapping maps a Java class to a BackingMap and allows a map to be included in a query. It also indicates whether the query engine should use a getter method or direct field access to access fields in the value class.

For example, class Department is the value class that is stored in the "DepartmentMap" BackingMap and the key is an Integer. 

 public class Department {
     private int id;
     private Collection emps;
     
     public void setEmps(Collection emps) {
         this.emps = emps;
     }
     
     public Collection getEmps() {
         return emps;
     }
     ...
 }
The QueryMapping would be created as follows: 

 ...
 QueryConfig queryConfig = new QueryConfig();
 queryConfig.addMapping(new QueryMapping(
     "DepartmentMap", Department.class.getName(), "id", QueryMapping.PROPERTY_ACCESS)
 objectGrid.setQueryConfig(queryConfig);
 ...

Since:
WAS XD 6.1, XC10

Field Summary
static int FIELD_ACCESS
          This constant indicates to use direct field access to read the field values
static int PROPERTY_ACCESS
          This constant indicates to use JavaBean property-style get methods to read the field values from the Java object stored in the BackingMap.
 
Constructor Summary
QueryMapping()
          Default constructor.
QueryMapping(java.lang.String mapName, java.lang.String valueClass, java.lang.String primaryKeyField)
          Constructor for creating a basic QueryMapping instance wiht a default access type of PROPERTY_ACCESS.
QueryMapping(java.lang.String mapName, java.lang.String valueClass, java.lang.String primaryKeyField, int accessType)
          Constructor for creating a QueryMapping instance.
 
Method Summary
boolean equals(java.lang.Object o)
           
int getAccessType()
          Retrieve the method in which the query engine will access the value class object stored in the BackingMap.
java.lang.String getMapName()
          Retrieve the BackingMap name associated with this mapping.
java.lang.String getPrimaryKeyField()
          Retrieve the name of the attribute in the value class object that is also the primary key of the BackingMap.
java.lang.String getValueClass()
          Retrieve the type of object that is stored in the BackingMap.
int hashCode()
           
void setAccessType(int accessType)
          Set the method in which the query engine will access the value class object stored in the BackingMap.
void setMapName(java.lang.String mapName)
          Set the BackingMap name associated with this mapping.
void setPrimaryKeyField(java.lang.String primaryKeyField)
          Set the name of the attribute in the value class object that is also the primary key of the BackingMap.
void setValueClass(java.lang.String valueClass)
          Set the type of object that is stored in the BackingMap.
java.lang.String toString()
           
 
Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

FIELD_ACCESS

public static final int FIELD_ACCESS

This constant indicates to use direct field access to read the field values

getAccessType(), Constant Field Values

PROPERTY_ACCESS

public static final int PROPERTY_ACCESS

This constant indicates to use JavaBean property-style get methods to read the field values from the Java object stored in the BackingMap. PROPERTY_ACCESS is the default.

getAccessType(), Constant Field Values
Constructor Detail

QueryMapping

public QueryMapping()

Default constructor.

QueryMapping

public QueryMapping(java.lang.String mapName,
                    java.lang.String valueClass,
                    java.lang.String primaryKeyField)

Constructor for creating a basic QueryMapping instance wiht a default access type of PROPERTY_ACCESS.

The mapName and valueClass must not be null.

Parameters:
mapName - the name of the BackingMap to map
valueClass - the class of object stored in the BackingMap's value.
primaryKeyField - the optional name of the primary key field of the class.

QueryMapping

public QueryMapping(java.lang.String mapName,
                    java.lang.String valueClass,
                    java.lang.String primaryKeyField,
                    int accessType)

Constructor for creating a QueryMapping instance. The mapName and valueClass must not be null.

Parameters:
mapName - the name of the BackingMap to map
valueClass - the class of object stored in the BackingMap's value.
primaryKeyField - the optional name of the primary key field of the class.
accessType - the method (PROPERTY_ACCESS or FIELD_ACCESS) in which the query engine will access the persistent data in the value object.
Method Detail

getMapName

public java.lang.String getMapName()

Retrieve the BackingMap name associated with this mapping.

Returns:
the BackingMap name.

setMapName

public void setMapName(java.lang.String mapName)

Set the BackingMap name associated with this mapping.

getValueClass

public java.lang.String getValueClass()

Retrieve the type of object that is stored in the BackingMap.

Returns:
the object type that is stored in the BackingMap's value.

setValueClass

public void setValueClass(java.lang.String valueClass)

Set the type of object that is stored in the BackingMap.

getAccessType

public int getAccessType()

Retrieve the method in which the query engine will access the value class object stored in the BackingMap.

FIELD_ACCESS

setAccessType

public void setAccessType(int accessType)

Set the method in which the query engine will access the value class object stored in the BackingMap.

FIELD_ACCESS

getPrimaryKeyField

public java.lang.String getPrimaryKeyField()

Retrieve the name of the attribute in the value class object that is also the primary key of the BackingMap.

This value is optional.

Returns:
the primaryKeyField.

setPrimaryKeyField

public void setPrimaryKeyField(java.lang.String primaryKeyField)

Set the name of the attribute in the value class object that is also the primary key of the BackingMap.

Parameters:
primaryKeyField - the name of the primary key attribute or null if not set.

equals

public boolean equals(java.lang.Object o)

Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:
hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:
toString in class java.lang.Object


com.ibm.websphere.objectgrid.config
Class QueryRelationship

java.lang.Object
  com.ibm.websphere.objectgrid.config.QueryRelationship

All Implemented Interfaces:
java.io.Serializable

public class QueryRelationship
extends java.lang.Object
implements java.io.Serializable

A QueryRelationship represents a relationship between two BackingMap value classes. A BackingMap must have one class type defined in the value part of the map. A relationship can be established between two maps by mapping the source and target map's value classes.

The cardinality of the relationship is automatically determined by the type of the attribute field.

A relationship requires two classes, a relationship field, and optionally an inverse realtionship field.

For example: Two entities; Department and Employee, have the following bi-directional relationship:

  1. One department has many employees. the collection field in the Department class is "emps"
  2. An employee belongs to one department 

 public class Department {
     private int id;
     private Collection emps;
     
     public void setEmps(Collection emps) {
         this.emps = emps;
     }
     
     public Collection getEmps() {
         return emps;
     }
     ...
 }
 
 public class Employee {
     private int id;
     private Department dept;
     
     public void setDept(Department dept) {
         this.dept = dept;
     }
     
     public Department getDept() {
         return dept;
     }
 }
Use the following method call to establish this bi-directional relationship. 

 queryConfig.addRelationship(new QueryRelationship(
     Department.class.getName(), Employee.class.getName(), "emps", "dept"));

Since:
WAS XD 6.1, XC10

Constructor Summary
QueryRelationship(java.lang.String sourceClass, java.lang.String targetClass, java.lang.String relationshipField, java.lang.String invRelationshipField)
          Constructor for creating a QueryRelationship instance.
 
Method Summary
boolean equals(java.lang.Object o)
           
java.lang.String getInvRelationshipField()
          Retrieve the inverse relationship attribute name of a bi-directional relationship.
java.lang.String getRelationshipField()
          Retrieve the name of the attribute in the source class that references the key of the target class.
java.lang.String getSourceClass()
          Retrieve the name of the class representing the source of a relationship.
java.lang.String getTargetClass()
          Retrieve the name of the class representing the target of a relationship.
int hashCode()
           
void setInvRelationshipField(java.lang.String invRelationshipField)
          Set the inverse relationship attribute name of a bi-directional relationship.
void setRelationshipField(java.lang.String relationshipField)
          Set the name of the attribute in the source class that references the key of the target class.
void setSourceClass(java.lang.String sourceClass)
          Set the name of the class representing the source of a relationship.
void setTargetClass(java.lang.String targetClass)
          Set the name of the class representing the target of a relationship.
java.lang.String toString()
           
 
Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

QueryRelationship

public QueryRelationship(java.lang.String sourceClass,
                         java.lang.String targetClass,
                         java.lang.String relationshipField,
                         java.lang.String invRelationshipField)

Constructor for creating a QueryRelationship instance.

The sourceClass, targetClass, and relationshipField must not be null.

Parameters:
sourceClass - the source class of the relationship
targetClass - the target class of the relationship
relationshipField - the attribute in the source class that references the key of the target class.
invRelationshipField - the attribute in the target class that references the key of the source class. This value is null if a bi-directional relationship does not exist.
Method Detail

getInvRelationshipField

public java.lang.String getInvRelationshipField()

Retrieve the inverse relationship attribute name of a bi-directional relationship.

Returns:
the attribute name of the inverse side of a bi-directional relationship or null if the relationship is uni-directional.

setInvRelationshipField

public void setInvRelationshipField(java.lang.String invRelationshipField)

Set the inverse relationship attribute name of a bi-directional relationship.

Parameters:
invRelationshipField - the attribute name of the inverse side of a bi-directional relationship or null if the relationship is uni-directional.

getRelationshipField

public java.lang.String getRelationshipField()

Retrieve the name of the attribute in the source class that references the key of the target class.

Returns:
the name of the relationship attribute.

setRelationshipField

public void setRelationshipField(java.lang.String relationshipField)

Set the name of the attribute in the source class that references the key of the target class.

Parameters:
relationshipField - the name of the relationship attribute.

getSourceClass

public java.lang.String getSourceClass()

Retrieve the name of the class representing the source of a relationship.

Returns:
the source class

setSourceClass

public void setSourceClass(java.lang.String sourceClass)

Set the name of the class representing the source of a relationship.

Parameters:
sourceClass - the source class

getTargetClass

public java.lang.String getTargetClass()

Retrieve the name of the class representing the target of a relationship.

Returns:
the target class

setTargetClass

public void setTargetClass(java.lang.String targetClass)

Set the name of the class representing the target of a relationship.

Parameters:
targetClass - the target class

equals

public boolean equals(java.lang.Object o)

Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:
hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:
toString in class java.lang.Object


Package com.ibm.websphere.objectgrid.management

This package contains the interfaces for all ObjectGrid MBeans.

See:
          Description

Interface Summary
AgentManagerMBean
This MBean interface allows a client process to access different attributes and statistical data about a specific Agent on a server process.
CatalogServiceManagementMBean
This MBean interface allows user to manipulate the behaviors of heartbeat and leader manager.
ContainerMBean
This MBean interface allows a client process to perform operations on and get status from an ObjectGrid container running in a dynamic environment.
DynamicServerMBean
This MBean interface allows a client process to access different attributes about a specific server process in a dynamic environment.
HashIndexMBean
This MBean interface allows a client process to access different attributes and statistical data about a specific HashIndex on a server process.
MapMBean
This MBean interface allows a client process to access different attributes and statistical data about a specific map on a server process.
ObjectGridMBean
This MBean interface allows a client process to access different attributes and statistical data about a specific ObjectGrid on a server process.
PlacementMediationServiceMBean
This MBean interface allows a client process to perform operations on and get status from the PlacementMediationService running in a dynamic environment.
PlacementServiceMBean
This MBean interface allows a client process to perform operations on and get status from the PlacementService running in a dynamic environment.
QueryManagerMBean
This MBean interface allows a client process to perform operations on and get status from an ObjectGrid Query Manager running in a dynamic environment.
QuorumManagerMBean
Each catalog service has a QuorumManager and an associated MBean.
ServerMBean
This MBean interface allows a client process to access different attributes about a specific server process.
SessionMBean
This MBean interface allows a client process to access different attributes and statistical data about a specific session.
ShardMBean
This MBean interface allows a client process to perform operations on and get status from a shard running in a dynamic environment.
ThreadPoolMBean
This MBean interface allows user to access the thread pool properties.
 


Package com.ibm.websphere.objectgrid.management Description

This package contains the interfaces for all ObjectGrid MBeans.


Overview

Each MBean interface has several methods to administer and monitor ObjectGrid services and components.


com.ibm.websphere.objectgrid.management
Interface AgentManagerMBean

public interface AgentManagerMBean

This MBean interface allows a client process to access different attributes and statistical data about a specific Agent on a server process. The Agent Manager MBean is scoped at the map level and therefore can access statistical data for every agent run against the specified map. In a dynamic ObjectGrid environment, the object name pattern for this MBean is: 

 com.ibm.websphere.objectgrid:type=AgentManager,name=Agent-<map>,partition=<partition id>,objectgrid=<objectgrid>,host=<host>,ogServerName=<server>
If ObjectGrid is running in a WebSphere Application Server process, more key=value pairs may be added to the object name.

Since:
WAS XD 6.1.0.5, XC10

Method Summary
double getAgentInflationTime(java.lang.String agentClassName)
          Gets the specified agent's inflation time attribute loaded up by the retrieveStatsModule() method.
double getAgentSerializationTime(java.lang.String agentClassName)
          Gets the specified agent's serialization time attribute loaded up by the retrieveStatsModule() method.
double getFailureCount(java.lang.String agentClassName)
          Gets the specified agent's failure count attribute loaded up by the retrieveStatsModule() method.
double getInvocationCount(java.lang.String agentClassName)
          Gets the specified agent's invocation count attribute loaded up by the retrieveStatsModule() method.
double getPartitionCount(java.lang.String agentClassName)
          Gets the specified agent's partition count attribute loaded up by the retrieveStatsModule() method.
double getReduceTime(java.lang.String agentClassName)
          Gets the specified agent's total reduce time attribute loaded up by the retrieveStatsModule() method.
double getResultInflationTime(java.lang.String agentClassName)
          Gets the specified agent's result inflation time attribute loaded up by the retrieveStatsModule() method.
double getResultSerializationTime(java.lang.String agentClassName)
          Gets the specified agent's result serialization time attribute loaded up by the retrieveStatsModule() method.
double getTotalDurationTime(java.lang.String agentClassName)
          Gets the specified agent's total run time attribute loaded up by the retrieveStatsModule() method.
AgentStatsModule retrieveStatsModule(java.lang.String agentClassName)
          Gets the AgentStatsModule used to retrieve statistics associated with the specified agent class
 

Method Detail

getReduceTime

double getReduceTime(java.lang.String agentClassName)

Gets the specified agent's total reduce time attribute loaded up by the retrieveStatsModule() method.

Parameters:
agentClassName - The fully qualified class name of the agent AgentStatsModule.getReduceTime(boolean copy)

getTotalDurationTime

double getTotalDurationTime(java.lang.String agentClassName)

Gets the specified agent's total run time attribute loaded up by the retrieveStatsModule() method.

Parameters:
agentClassName - The fully qualified class name of the agent AgentStatsModule.getTotalDurationTime(boolean copy)

getAgentSerializationTime

double getAgentSerializationTime(java.lang.String agentClassName)

Gets the specified agent's serialization time attribute loaded up by the retrieveStatsModule() method.

Parameters:
agentClassName - The fully qualified class name of the agent AgentStatsModule.getAgentSerializationTime(boolean copy)

getAgentInflationTime

double getAgentInflationTime(java.lang.String agentClassName)

Gets the specified agent's inflation time attribute loaded up by the retrieveStatsModule() method.

Parameters:
agentClassName - The fully qualified class name of the agent AgentStatsModule.getAgentInflationTime(boolean copy)

getResultInflationTime

double getResultInflationTime(java.lang.String agentClassName)

Gets the specified agent's result inflation time attribute loaded up by the retrieveStatsModule() method.

Parameters:
agentClassName - The fully qualified class name of the agent AgentStatsModule.getResultInflationTime(boolean copy)

getResultSerializationTime

double getResultSerializationTime(java.lang.String agentClassName)

Gets the specified agent's result serialization time attribute loaded up by the retrieveStatsModule() method.

Parameters:
agentClassName - The fully qualified class name of the agent AgentStatsModule.getResultSerializationTime(boolean copy)

getPartitionCount

double getPartitionCount(java.lang.String agentClassName)

Gets the specified agent's partition count attribute loaded up by the retrieveStatsModule() method.

Parameters:
agentClassName - The fully qualified class name of the agent AgentStatsModule.getPartitionCount(boolean copy)

getFailureCount

double getFailureCount(java.lang.String agentClassName)

Gets the specified agent's failure count attribute loaded up by the retrieveStatsModule() method.

Parameters:
agentClassName - The fully qualified class name of the agent AgentStatsModule.getFailureCount(boolean copy)

getInvocationCount

double getInvocationCount(java.lang.String agentClassName)

Gets the specified agent's invocation count attribute loaded up by the retrieveStatsModule() method.

Parameters:
agentClassName - The fully qualified class name of the agent AgentStatsModule.getInvocationCount(boolean copy)

retrieveStatsModule

AgentStatsModule retrieveStatsModule(java.lang.String agentClassName)

Gets the AgentStatsModule used to retrieve statistics associated with the specified agent class

Parameters:
agentClassName - The fully qualified class name of the agent


com.ibm.websphere.objectgrid.management
Interface CatalogServiceManagementMBean

public interface CatalogServiceManagementMBean

This MBean interface allows user to manipulate the behaviors of heartbeat and leader manager. The object name pattern for this MBean is: 

 com.ibm.websphere.objectgrid:type=CatalogService
If ObjectGrid is running in a WebSphere Application Server process, more key=value pairs may be added to the object name.

Since:
7.1, XC10

Field Summary
static java.lang.String COREGROUP_MEMBERSHIP_CHANGE
          Constant representing a core group membership change notification.
static int HEARTBEAT_FREQUENCY_LEVEL_AGGRESSIVE
          Constant representing a heartbeat frequency level at an aggressive rate.
static int HEARTBEAT_FREQUENCY_LEVEL_RELAXED
          Constant representing a heartbeat frequency level at relaxed rate.
static int HEARTBEAT_FREQUENCY_LEVEL_TYPICAL
          Constant representing a heartbeat frequency level at a typical rate.
static java.lang.String SERVER_EVENT_STARTED
          Constant representing a WXS server start notification.
static java.lang.String SERVER_EVENT_STOPPED
          Constant representing a WXS server stop notification.
 
Method Summary
int getHeartBeatFrequencyLevel()
          Retrieves the heartbeat frequency level.
int getNumberOfServers()
          Retrieves the number eXtreme Scale servers that are currently registered with the catalog service.
javax.management.openmbean.CompositeData getServers()
          Retrieves a CompositeData of each eXtreme Scale server that is currently registered with the catalog service.
 

Field Detail

COREGROUP_MEMBERSHIP_CHANGE

static final java.lang.String COREGROUP_MEMBERSHIP_CHANGE

Constant representing a core group membership change notification. The user data associated with this notification is a CompositeData.

The CompositeData includes the following items:
Item NameTypeDescription

MemberName
String
The name of the server that is included in the core group.

SERVER_EVENT_STARTED

static final java.lang.String SERVER_EVENT_STARTED

Constant representing a WXS server start notification.

The UserData argument of the Notification includes a TabularData that includes information for each of the servers. Each CompositeData (row in the TabularData) contains the following items:
Item NameTypeDescription

HAPort
String
The port number of the high availability manager.

Host
String
The host/ip address of the server.

JMXServiceURL
String
The JMX service url used to access the server.

ServerName
String
The name of the server.

ZoneName
String
The name of the zone that the server belongs.

SERVER_EVENT_STOPPED

static final java.lang.String SERVER_EVENT_STOPPED

Constant representing a WXS server stop notification.

The UserData argument of the Notification includes a TabularData instance where each CompositeData contains the following items:
Item NameTypeDescription

ServerName
String
The name of the server.

HEARTBEAT_FREQUENCY_LEVEL_TYPICAL

static final int HEARTBEAT_FREQUENCY_LEVEL_TYPICAL

Constant representing a heartbeat frequency level at a typical rate.

A typical heartbeat frequency allows reasonable failover detection and resource utilization. This value is the default.

HEARTBEAT_FREQUENCY_LEVEL_AGGRESSIVE

static final int HEARTBEAT_FREQUENCY_LEVEL_AGGRESSIVE

Constant representing a heartbeat frequency level at an aggressive rate.

An increased heartbeat frequency allows failures to be detected more quickly, but can also uses additional CPU and network resources. This level is more sensitive to missing heartbeats when the server is stressed.

HEARTBEAT_FREQUENCY_LEVEL_RELAXED

static final int HEARTBEAT_FREQUENCY_LEVEL_RELAXED

Constant representing a heartbeat frequency level at relaxed rate.

A decreased heartbeat frequency increases the time to detect failures, but also decreases CPU and network utilization.

Method Detail

getHeartBeatFrequencyLevel

int getHeartBeatFrequencyLevel()

Retrieves the heartbeat frequency level.

Valid values include:

Returns:
the heartbeat frequency level: -1, 0 or 1 as defined by the constants that begin with name HEARTBEAT_FREQUENCY_LEVEL.

getServers

javax.management.openmbean.CompositeData getServers()

Retrieves a CompositeData of each eXtreme Scale server that is currently registered with the catalog service.

The CompositeData includes the following items:
Item NameTypeDescription

serverName
String
The name of the server that is registered with the catalog service.

Returns:
the CompositeData representing the currently registered eXtreme Scale servers.

getNumberOfServers

int getNumberOfServers()

Retrieves the number eXtreme Scale servers that are currently registered with the catalog service.

Returns:
the number of registered eXtreme Scale servers.


com.ibm.websphere.objectgrid.management
Interface ContainerMBean

public interface ContainerMBean

This MBean interface allows a client process to perform operations on and get status from an ObjectGrid container running in a dynamic environment. The object name pattern for this MBean is: 

 com.ibm.websphere.objectgrid:type=ObjectGridContainer,name=<server>,host=<host>,ogServerName=<server>
If ObjectGrid is running in a WebSphere Application Server process, more key=value pairs may be added to the object name.

Since:
WAS XD 6.1 FIX3, XC10

Field Summary
static java.lang.String INVALID_PARTITION
          INVALID_PARTITION indicates that no partition was found for the requested shard.
static java.lang.String MAPSET_UNSUPPORTED_ON_CONTAINER
          MAPSET_UNSUPPORTED_ON_CONTAINER indicates that an attempt was made to reserve a shard from a map set that is not supported on this container.
static java.lang.String QUIESCE_COMPLETE
          QUIESCE_COMPLETE is the MBean notification type for a completed quiesce.
static java.lang.String RELEASE_SUCCESSFUL
          RELEASE_SUCCESSFUL indicates that the attempt to release the shard was successful.
static java.lang.String RELEASE_UNSUPPORTED_WITH_PER_CONTAINER
          RELEASE_UNSUPPORTED_WITH_PER_CONTAINER indicates that the shard is part of a map set using the PER_CONTAINER placement strategy.
static java.lang.String RESERVATION_PRIOR_TO_INITIAL_PLACEMENT
          RESERVATION_PRIOR_TO_INITIAL_PLACEMENT indicates that the attempt to reserve the shard was processed successfully.
static java.lang.String RESERVATION_SUCCESSFUL
          RESERVATION_SUCCESSFUL indicates that the attempt to reserve the shard was successful.
static java.lang.String RESERVE_UNSUPPORTED_WITH_PER_CONTAINER
          RESERVE_UNSUPPORTED_WITH_PER_CONTAINER indicates that the shard is part of a map set using the PER_CONTAINER placement strategy.
static java.lang.String SHARD_ALREADY_RESERVED
          SHARD_ALREADY_RESERVED indicates that the shard is already reserved elsewhere and cannot be reserved on the specified container.
static java.lang.String SHARD_NOT_RESERVED_ON_CONTAINER
          SHARD_NOT_RESERVED_ON_CONTAINER indicates that the attempt to release the shard from the requesting container failed because the specified shard was not found to be reserved by the requesting container.
 
Method Summary
int getActivatedShardCount()
          Retrieve the total number of shards that have been activated for the life of this ObjectGrid container.
int getActiveShardCount()
          Retrieve the number of active shards hosted in this ObjectGrid container.
java.lang.String getContainerName()
          Retrieve the name of the container.
int getDeactivatedShardCount()
          Retrieve the total number of shards that have been deactivated for the life of this ObjectGrid container.
java.lang.String getDomainName()
          Retrieve the name of the catalog server grouping administering this container.
java.lang.String getStatus()
          Retrieve the status information for the shards in this container.
java.lang.String getZoneName()
          Retrieve the name of the zone grouping that this container belongs to.
int quiesceContainer(java.lang.Boolean inQuiesce)
          Prepare the container for a potential shutdown by moving replica shards, verifying that primaries have required sync replicas and preventing the placement of new shards.
java.lang.String release(java.lang.String objectGridName, java.lang.String mapSetName, java.lang.String partitionName)
          Release a shard that has been previously reserved by this container.
java.lang.String reserve(java.lang.String objectGridName, java.lang.String mapSetName, java.lang.String partitionName, java.lang.String shardType)
          Reserve a specific shard on this container.
java.lang.String retrieveStatus(java.lang.String objectGridName, java.lang.String mapSetName)
          Retrieve the status information for the shards in this container, filtered by ObjectGrid and/or mapset.
void teardown()
          Tears down and stops the container in a way to allow partitions to be moved to new locations.
void terminate()
          Terminates a container without coordinating partition movement, partitions will failover.
 

Field Detail

QUIESCE_COMPLETE

static final java.lang.String QUIESCE_COMPLETE

QUIESCE_COMPLETE is the MBean notification type for a completed quiesce.

Constant Field Values

RESERVATION_SUCCESSFUL

static final java.lang.String RESERVATION_SUCCESSFUL

RESERVATION_SUCCESSFUL indicates that the attempt to reserve the shard was successful. The shard is reserved by the requesting container.

Since:
7.0.0.0 FIX1
Constant Field Values

RESERVATION_PRIOR_TO_INITIAL_PLACEMENT

static final java.lang.String RESERVATION_PRIOR_TO_INITIAL_PLACEMENT

RESERVATION_PRIOR_TO_INITIAL_PLACEMENT indicates that the attempt to reserve the shard was processed successfully. However, since initial placement has not yet occurred, the reserved shard is not immediately moved to the requesting container. The shard will be placed on the container when initial placement is triggered.

Since:
7.0.0.0 FIX1
Constant Field Values

SHARD_ALREADY_RESERVED

static final java.lang.String SHARD_ALREADY_RESERVED

SHARD_ALREADY_RESERVED indicates that the shard is already reserved elsewhere and cannot be reserved on the specified container. The shard must be released from the owning container before it can be reserved again.

Since:
7.0.0.0 FIX1
Constant Field Values

INVALID_PARTITION

static final java.lang.String INVALID_PARTITION

INVALID_PARTITION indicates that no partition was found for the requested shard.

Since:
7.0.0.0 FIX1
Constant Field Values

RESERVE_UNSUPPORTED_WITH_PER_CONTAINER

static final java.lang.String RESERVE_UNSUPPORTED_WITH_PER_CONTAINER

RESERVE_UNSUPPORTED_WITH_PER_CONTAINER indicates that the shard is part of a map set using the PER_CONTAINER placement strategy. Shard reservation is not supported with this placement strategy.

Since:
7.0.0.0 FIX1
Constant Field Values

RELEASE_SUCCESSFUL

static final java.lang.String RELEASE_SUCCESSFUL

RELEASE_SUCCESSFUL indicates that the attempt to release the shard was successful. The shard is no longer reserved by this container. The shard is free to migrate, but it is not forced to migrate.

Since:
7.0.0.0 FIX1
Constant Field Values

SHARD_NOT_RESERVED_ON_CONTAINER

static final java.lang.String SHARD_NOT_RESERVED_ON_CONTAINER

SHARD_NOT_RESERVED_ON_CONTAINER indicates that the attempt to release the shard from the requesting container failed because the specified shard was not found to be reserved by the requesting container. Only the container owning the reservation may release a shard.

Since:
7.0.0.0 FIX1
Constant Field Values

RELEASE_UNSUPPORTED_WITH_PER_CONTAINER

static final java.lang.String RELEASE_UNSUPPORTED_WITH_PER_CONTAINER

RELEASE_UNSUPPORTED_WITH_PER_CONTAINER indicates that the shard is part of a map set using the PER_CONTAINER placement strategy. Shard release is not supported with this placement strategy.

Since:
7.0.0.0 FIX1
Constant Field Values

MAPSET_UNSUPPORTED_ON_CONTAINER

static final java.lang.String MAPSET_UNSUPPORTED_ON_CONTAINER

MAPSET_UNSUPPORTED_ON_CONTAINER indicates that an attempt was made to reserve a shard from a map set that is not supported on this container. Only map sets that were included in the deployment policy at container initialization are supported to run on this container.

Since:
7.1
Constant Field Values
Method Detail

teardown

void teardown()

Tears down and stops the container in a way to allow partitions to be moved to new locations.

terminate

void terminate()

Terminates a container without coordinating partition movement, partitions will failover.

getActiveShardCount

int getActiveShardCount()

Retrieve the number of active shards hosted in this ObjectGrid container.

Returns:
The current number of active shards.

getActivatedShardCount

int getActivatedShardCount()

Retrieve the total number of shards that have been activated for the life of this ObjectGrid container.

Returns:
The number of activated shards.

getDeactivatedShardCount

int getDeactivatedShardCount()

Retrieve the total number of shards that have been deactivated for the life of this ObjectGrid container.

Returns:
The number of deactivated shards

getDomainName

java.lang.String getDomainName()

Retrieve the name of the catalog server grouping administering this container.

Returns:
The domain name.

getZoneName

java.lang.String getZoneName()

Retrieve the name of the zone grouping that this container belongs to.

Returns:
The name of the zone.

quiesceContainer

int quiesceContainer(java.lang.Boolean inQuiesce)

Prepare the container for a potential shutdown by moving replica shards, verifying that primaries have required sync replicas and preventing the placement of new shards.

Parameters:
inQuiesce - Initiate quiesce mode (true) or cancel quiesce mode (false)

getStatus

java.lang.String getStatus()

Retrieve the status information for the shards in this container.

Returns:
The status information for the shards in this container.

retrieveStatus

java.lang.String retrieveStatus(java.lang.String objectGridName,
                                java.lang.String mapSetName)

Retrieve the status information for the shards in this container, filtered by ObjectGrid and/or mapset. For example, calling retrieveStatus with "og1" and "ms1" as parameters will return the partition status for those partitions in ObjectGrid og1 and mapset ms1. Passing in an empty string ("") objectGridName or mapSetName will return all of the partitions, since the empty string acts as a wildcard. Passing in the empty string for both parameters will return the same status as calling getStatus().

Parameters:
objectGridName - The name of the ObjectGrid for which the status is requested.
mapSetName - The name of the mapset within the ObjectGrid for which the status is requested.
Returns:
The status information for the shards in this container.

reserve

java.lang.String reserve(java.lang.String objectGridName,
                         java.lang.String mapSetName,
                         java.lang.String partitionName,
                         java.lang.String shardType)

Reserve a specific shard on this container. Calling this method will cause the requested shard to move to this container. The shard can be moved to this container only if it is not reserved elsewhere. Calling this method prior to initial placement will pre-reserve the shard so that it will be placed onto this container when initial placement occurs. If non-reserved shard for the same partition is on this container prior to reservation, the non-reserved shard will be moved off the container upon reservation. A reserved shard will not be moved off of this container until it is released or the container is stopped.

Parameters:
objectGridName - the ObjectGrid containing the shard
mapSetName - the map set containing the shard
partitionName - the partition containing the shard
shardType - the type of shard. Currently, only primary shards can be reserved: ShardMBean.TYPE_PRIMARY
Returns:
the return code indicating the result of the reserve request
Throws:
java.lang.IllegalArgumentException - if any of the arguments are null or the empty String. Also thrown if shardType is not ShardMBean.TYPE_PRIMARY
Since:
7.0.0.0 FIX1
release(String, String, String), RESERVATION_SUCCESSFUL, RESERVATION_PRIOR_TO_INITIAL_PLACEMENT, SHARD_ALREADY_RESERVED, INVALID_PARTITION, RESERVE_UNSUPPORTED_WITH_PER_CONTAINER

release

java.lang.String release(java.lang.String objectGridName,
                         java.lang.String mapSetName,
                         java.lang.String partitionName)

Release a shard that has been previously reserved by this container. This container can only release shards that it has reserved. Releasing the shard does not guarantee the shard will be moved. The shard may remain on this container. However, it will not be explicitly bound to this container. Releasing a shard allows the shard to move freely to other containers or to be reserved by another container.

Parameters:
objectGridName - the ObjectGrid containing the shard
mapSetName - the map set containing the shard
partitionName - the partition containing the shard
Returns:
the return code indicating the result of the release request
Throws:
java.lang.IllegalArgumentException - if any of the arguments are null or the empty String
Since:
7.0.0.0 FIX1
RELEASE_SUCCESSFUL, SHARD_NOT_RESERVED_ON_CONTAINER, RELEASE_UNSUPPORTED_WITH_PER_CONTAINER

getContainerName

java.lang.String getContainerName()

Retrieve the name of the container. The container name is based on the server name and includes a suffix which uniquely identifies the container within the server.

Returns:
the name of the container
Since:
7.1


com.ibm.websphere.objectgrid.management
Interface DynamicServerMBean

All Superinterfaces:
ServerMBean

public interface DynamicServerMBean
extends ServerMBean

This MBean interface allows a client process to access different attributes about a specific server process in a dynamic environment. The object name pattern for this MBean is: 

 com.ibm.websphere.objectgrid:type=ObjectGridServer,name=<server>,host=<host>,ogServerName=<server>
If ObjectGrid is running in a WebSphere Application Server process, more key=value pairs may be added to the object name.

Since:
WAS XD 6.1 FIX3, XC10

Field Summary
static java.lang.String SERVER_COREGROUP_MEMBERSHIP_CHANGE
           
 
Method Summary
int getAvailableProcessors()
          Returns the number of available processors for the JVM hosting this server.
long getFreeMemory()
          Returns the available memory in bytes for the JVM hosting this server.
java.lang.String getHostName()
          Returns the host name for this process.
long getMaxMemory()
          Returns the maximum memory in bytes for the JVM hosting this server.
boolean getSafeToShutdown()
          Returns true if a replica exists for each primary hosted on this server.
java.lang.String getStatsSpec()
          Retrieve the current statistics specification for the server.
long getTotalMemory()
          Returns the total memory in bytes for the JVM hosting this server.
java.lang.String getTraceSpec()
          Retrieve the current trace specification for the server.
java.lang.String getZoneName()
          Returns the zone name for this process
void setStatsSpec(java.lang.String statsSpec)
          Set the statistics specification for the server.
void setTraceSpec(java.lang.String traceSpec)
          Set the trace specification for the server.
 
Methods inherited from interface com.ibm.websphere.objectgrid.management.ServerMBean

getServerName, modifyServerTraceSpec, stopServer
 

Field Detail

SERVER_COREGROUP_MEMBERSHIP_CHANGE

static final java.lang.String SERVER_COREGROUP_MEMBERSHIP_CHANGE

Method Detail

getAvailableProcessors

int getAvailableProcessors()

Returns the number of available processors for the JVM hosting this server.

getFreeMemory

long getFreeMemory()

Returns the available memory in bytes for the JVM hosting this server.

getMaxMemory

long getMaxMemory()

Returns the maximum memory in bytes for the JVM hosting this server.

getTotalMemory

long getTotalMemory()

Returns the total memory in bytes for the JVM hosting this server.

getHostName

java.lang.String getHostName()

Returns the host name for this process.

getZoneName

java.lang.String getZoneName()

Returns the zone name for this process

Returns:
the zone name that was included in the properties used to start the server or DefaultZone if no zone name was used

getSafeToShutdown

boolean getSafeToShutdown()

Returns true if a replica exists for each primary hosted on this server. Returns false if the server has the only copy of data.

Returns:
If server is safe to shutdown.

getStatsSpec

java.lang.String getStatsSpec()

Retrieve the current statistics specification for the server.

Returns:
a string representation of the statistics specification.
Since:
7.1

setStatsSpec

void setStatsSpec(java.lang.String statsSpec)

Set the statistics specification for the server.

Parameters:
statsSpec - the statistics specification string.
Since:
7.1

getTraceSpec

java.lang.String getTraceSpec()

Retrieve the current trace specification for the server.

Returns:
the trace specification string.
Since:
7.1

setTraceSpec

void setTraceSpec(java.lang.String traceSpec)

Set the trace specification for the server.

Parameters:
traceSpec - the statistics specification string.
Since:
7.1


com.ibm.websphere.objectgrid.management
Interface HashIndexMBean

public interface HashIndexMBean

This MBean interface allows a client process to access different attributes and statistical data about a specific HashIndex on a server process. In a dynamic ObjectGrid environment, the object name pattern for this MBean is: 

 com.ibm.websphere.objectgrid:type=HashIndex,name=<index-name>,partition=<partition id>,objectgrid=<objectgrid>,host=<host>,ogServerName=<server>
If ObjectGrid is running in a WebSphere Application Server process, more key=value pairs may be added to the object name.

Since:
WAS XD 6.1.0.5, XC10

Method Summary
double getBatchUpdateCount()
          Gets the index's batchupdate count attribute loaded up by the retrieveStatsModule() method.
double getFindCollisionCount()
          Gets the index's collision count attribute loaded up by the retrieveStatsModule() method.
double getFindCount()
          Gets the index's find count attribute loaded up by the retrieveStatsModule() method.
double getFindDurationTime()
          Gets the index's find duration time attribute loaded up by the retrieveStatsModule() method.
double getFindFailureCount()
          Gets the index's failure count attribute loaded up by the retrieveStatsModule() method.
double getFindResultCount()
          Gets the index's result count attribute loaded up by the retrieveStatsModule() method.
java.lang.String getParentMapName()
          Gets the index's parent map name
HashIndexStatsModule retrieveStatsModule()
          Gets the HashIndexStatsModule used to retrieve statistics associated with this index
 

Method Detail

getParentMapName

java.lang.String getParentMapName()

Gets the index's parent map name

Returns:
the name of the map which this index belongs to

retrieveStatsModule

HashIndexStatsModule retrieveStatsModule()

Gets the HashIndexStatsModule used to retrieve statistics associated with this index

getFindCount

double getFindCount()

Gets the index's find count attribute loaded up by the retrieveStatsModule() method.

HashIndexStatsModule.getFindCount(boolean copy)

getFindDurationTime

double getFindDurationTime()

Gets the index's find duration time attribute loaded up by the retrieveStatsModule() method.

HashIndexStatsModule.getFindDurationTime(boolean copy)

getFindResultCount

double getFindResultCount()

Gets the index's result count attribute loaded up by the retrieveStatsModule() method.

HashIndexStatsModule.getFindResultCount(boolean copy)

getFindFailureCount

double getFindFailureCount()

Gets the index's failure count attribute loaded up by the retrieveStatsModule() method.

HashIndexStatsModule.getFindFailureCount(boolean copy)

getFindCollisionCount

double getFindCollisionCount()

Gets the index's collision count attribute loaded up by the retrieveStatsModule() method.

HashIndexStatsModule.getFindCollisionCount(boolean copy)

getBatchUpdateCount

double getBatchUpdateCount()

Gets the index's batchupdate count attribute loaded up by the retrieveStatsModule() method.

MapIndexPlugin.doBatchUpdate(TxID txid, LogSequence sequence), HashIndexStatsModule.getBatchUpdateCount(boolean copy)


com.ibm.websphere.objectgrid.management
Interface MapMBean

public interface MapMBean

This MBean interface allows a client process to access different attributes and statistical data about a specific map on a server process. In a dynamic ObjectGrid environment, the object name pattern for this MBean is: 

 com.ibm.websphere.objectgrid:type=ObjectMap,name=<map>,partition=<partition id>,objectgrid=<objectgrid>,host=<host>,ogServerName=<server>
If ObjectGrid is running in a WebSphere Application Server process, more key=value pairs may be added to the object name.

Since:
WAS XD 6.0.1, XC10

Method Summary
double getMapBatchUpdateMaxTime()
          Gets the maximum batch update time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.
double getMapBatchUpdateMeanTime()
          Gets the mean batch update time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.
double getMapBatchUpdateMinTime()
          Gets the minimum batch update time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.
double getMapBatchUpdateTotalTime()
          Gets the total batch update time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.
long getMapCountStatistic()
          Gets the map count attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.
long getMapGetCountStatistic()
          Gets the get count attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.
long getMapHitCountStatistic()
          Gets the hit count attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.
double getMapHitRateStatistic()
          Gets the hit rate attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.
java.lang.String getMapName()
          Gets the name of the map associated with this MBean.
java.lang.String getMapStatsModule()
          Gets a string representation of the MapStatsModule attributes loaded up by the retrieveStatsModule() or refreshStatsModule() method.
long getMapUsedBytes()
          Gets the used bytes attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.
java.lang.String getObjectGridName()
          Gets the name of the ObjectGrid containing the map associated with this MBean.
int getPartitionId()
          Retrieves the partition identifier for this map instance.
java.lang.String getServerName()
          Gets the name of the server containing the replication group member for the map associated with this MBean.
javax.management.openmbean.TabularData retrieveEntries(java.lang.String regex)
          Operation to iterate through all of the entries in this map, convert the key to string form, then match the string against the regular expression if passed, finally return the matching entries.
MapStatsModule retrieveStatsModule()
          Gets the MapStatsModule used to retrieve statistics associated with the map for this MBean.
 

Method Detail

retrieveStatsModule

MapStatsModule retrieveStatsModule()

Gets the MapStatsModule used to retrieve statistics associated with the map for this MBean.

MapStatsModule

getMapName

java.lang.String getMapName()

Gets the name of the map associated with this MBean.

Returns:
The name of the map.

getObjectGridName

java.lang.String getObjectGridName()

Gets the name of the ObjectGrid containing the map associated with this MBean.

Returns:
The name of the ObjectGrid for the map associated with this MBean.

getServerName

java.lang.String getServerName()

Gets the name of the server containing the replication group member for the map associated with this MBean.

Returns:
The name of server containing the replication group member for the map associated with this MBean.

getMapStatsModule

java.lang.String getMapStatsModule()

Gets a string representation of the MapStatsModule attributes loaded up by the retrieveStatsModule() or refreshStatsModule() method.

retrieveStatsModule(), MapStatsModule

getMapCountStatistic

long getMapCountStatistic()

Gets the map count attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.

retrieveStatsModule(), MapStatsModule.getNumEntries(boolean)

getMapHitRateStatistic

double getMapHitRateStatistic()

Gets the hit rate attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.

retrieveStatsModule(), MapStatsModule.getHitRate(boolean)

getMapGetCountStatistic

long getMapGetCountStatistic()

Gets the get count attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.

Returns:
The get count for the map.
Since:
7.1
retrieveStatsModule(), MapStatsModule.getHitRate(boolean)

getMapUsedBytes

long getMapUsedBytes()

Gets the used bytes attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.

The used bytes statistics are accurate only when we are using simple objects or the COPY_TO_BYTES copy mode.

Returns:
The number of bytes in use by the map.
Since:
7.1
retrieveStatsModule(), MapStatsModule.getUsedBytes(boolean)

getMapHitCountStatistic

long getMapHitCountStatistic()

Gets the hit count attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.

Returns:
The hit count for the map.
Since:
7.1
retrieveStatsModule(), MapStatsModule.getHitRate(boolean)

getMapBatchUpdateMeanTime

double getMapBatchUpdateMeanTime()

Gets the mean batch update time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.

retrieveStatsModule(), MapStatsModule.getBatchUpdateTime(boolean)

getMapBatchUpdateMaxTime

double getMapBatchUpdateMaxTime()

Gets the maximum batch update time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.

retrieveStatsModule(), MapStatsModule.getBatchUpdateTime(boolean)

getMapBatchUpdateMinTime

double getMapBatchUpdateMinTime()

Gets the minimum batch update time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.

retrieveStatsModule(), MapStatsModule.getBatchUpdateTime(boolean)

getMapBatchUpdateTotalTime

double getMapBatchUpdateTotalTime()

Gets the total batch update time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.

retrieveStatsModule(), MapStatsModule.getBatchUpdateTime(boolean)

getPartitionId

int getPartitionId()

Retrieves the partition identifier for this map instance.

Returns:
The partition identifier.
Since:
WAS XD 6.1.0.4

retrieveEntries

javax.management.openmbean.TabularData retrieveEntries(java.lang.String regex)

Operation to iterate through all of the entries in this map, convert the key to string form, then match the string against the regular expression if passed, finally return the matching entries. This method could potentially return a very large data structure so care should be taken to ensure the regular expression will reduce the number of keys appropriately.

Each CompositeData (row in the TabularData) contains the following items:
Item NameTypeDescription

KeyName
String
The domain name of this ObjectGrid shard.

LifetimeIndex
Short
The lifetime index for revisioning.

Revision
Long
The revision number of the last update.

Parameters:
regex - the regular expression to apply to the String form of the key. It should be used in narrowing the entries returned. If null, all entries are returned.
Returns:
A table of entries containing the user readable (String) form of the key and some meta information about the entry.
Since:
7.1.1


com.ibm.websphere.objectgrid.management
Interface ObjectGridMBean

public interface ObjectGridMBean

This MBean interface allows a client process to access different attributes and statistical data about a specific ObjectGrid on a server process. In a dynamic ObjectGrid environment, the object name pattern for this MBean is: 

 com.ibm.websphere.objectgrid:type=ObjectGrid,name=<objectgrid>,mapset=<mapset>,partition=<partition id>,host=<host>,ogServerName=<server>
If ObjectGrid is running in a WebSphere Application Server process, more key=value pairs may be added to the object name.

Since:
WAS XD 6.0.1, XC10

Method Summary
long getCurrentRevision()
          Retrieves the current revision number of this ObjectGrid shard.
java.lang.String getDomainName()
          Retrieves the domain name of this ObjectGrid shard.
javax.management.openmbean.TabularData getKnownRevisions()
          An ObjectGrid shard may exist over several different lifetimes.
java.lang.String getLifetimeId()
          Retrieves the lifetime id for this ObjectGrid shard.
java.lang.String getObjectGridName()
          Gets the name of the ObjectGrid associated with this MBean.
long getOGCount()
          Gets the ObjectGrid count attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.
long getOGMaxTranTime()
          Gets the maximum transaction time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.
double getOGMeanTranTime()
          Gets the mean transaction time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.
long getOGMinTranTime()
          Gets the minimum transaction time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.
java.lang.String getOGStatsModule()
          Gets a string representation of the OGStatsModule attributes loaded up by the retrieveStatsModule() or refreshStatsModule() method.
long getOGTotalTranTime()
          Gets the total transaction time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.
long getOGTransPerSecond()
          Transactions per second attribute loaded up by the retrieveStatsModule call.
javax.management.openmbean.TabularData getPrimaryShardLinks()
          Get the shard's list of foreign or domestic linked primaries.
java.lang.String getServerName()
          Gets the name of the server containing the replication group member for the ObjectGrid associated with this MBean.
OGStatsModule retrieveStatsModule()
          Gets the OGStatsModule used to retrieve statistics associated with the ObjectGrid for this MBean.
 

Method Detail

retrieveStatsModule

OGStatsModule retrieveStatsModule()

Gets the OGStatsModule used to retrieve statistics associated with the ObjectGrid for this MBean.

OGStatsModule

getObjectGridName

java.lang.String getObjectGridName()

Gets the name of the ObjectGrid associated with this MBean.

Returns:
name of the ObjectGrid

getServerName

java.lang.String getServerName()

Gets the name of the server containing the replication group member for the ObjectGrid associated with this MBean.

Returns:
the name of server containing the replication group member for the ObjectGrid associated with this MBean.

getOGStatsModule

java.lang.String getOGStatsModule()

Gets a string representation of the OGStatsModule attributes loaded up by the retrieveStatsModule() or refreshStatsModule() method.

retrieveStatsModule(), OGStatsModule

getOGCount

long getOGCount()

Gets the ObjectGrid count attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.

retrieveStatsModule(), OGStatsModule.getTransactionTime(String, boolean)

getOGMaxTranTime

long getOGMaxTranTime()

Gets the maximum transaction time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.

retrieveStatsModule(), OGStatsModule.getTransactionTime(String, boolean)

getOGMinTranTime

long getOGMinTranTime()

Gets the minimum transaction time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.

retrieveStatsModule(), OGStatsModule.getTransactionTime(String, boolean)

getOGMeanTranTime

double getOGMeanTranTime()

Gets the mean transaction time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.

retrieveStatsModule(), OGStatsModule.getTransactionTime(String, boolean)

getOGTotalTranTime

long getOGTotalTranTime()

Gets the total transaction time attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.

retrieveStatsModule(), OGStatsModule.getTransactionTime(String, boolean)

getOGTransPerSecond

long getOGTransPerSecond()

Transactions per second attribute loaded up by the retrieveStatsModule call. retrieveStatsModule() or refreshStatsModule() method.

retrieveStatsModule(), OGStatsModule.getTransactionTime(String, boolean)

getCurrentRevision

long getCurrentRevision()

Retrieves the current revision number of this ObjectGrid shard.

Returns:
the current revision number of this ObjectGrid shard.
Since:
7.1

getDomainName

java.lang.String getDomainName()

Retrieves the domain name of this ObjectGrid shard.

Returns:
the name of the domain name of this ObjectGrid shard.
Since:
7.1

getLifetimeId

java.lang.String getLifetimeId()

Retrieves the lifetime id for this ObjectGrid shard.

Returns:
the lifetime id for this ObjectGrid shard.
Since:
7.1

getKnownRevisions

javax.management.openmbean.TabularData getKnownRevisions()

An ObjectGrid shard may exist over several different lifetimes. As such, each shard instance will have a unique lifetime id and revision number associated with it. This method returns a TabularData object representing the known history of revision numbers for each lifetime. Each CompositeData (row in the TabularData) contains the following items:
Item NameTypeDescription

Domain
String
The domain name of this ObjectGrid shard.

LifetimeId
String
The lifetime id of this ObjectGrid shard.

Revision
Long
The revision of this ObjectGrid shard.

Returns:
TabularData representing the known lifetimes and revisions of this shard.
Throws:
javax.management.openmbean.OpenDataException
Since:
7.1

getPrimaryShardLinks

javax.management.openmbean.TabularData getPrimaryShardLinks()

Get the shard's list of foreign or domestic linked primaries.

This method returns a TabularData object representing the current state of each primary shard link.

Each CompositeData (row in the TabularData) contains the following items:
Item NameTypeDescription

RemoteDomain
String
The catalog service domain name of the remote primary shard..

RemoteContainer
String
The container name of the remote primary shard.

Status
String
The status of the link. Valid states include: online and recovery.

Returns:
TabularData representing the linked primaries
Since:
7.1.1


com.ibm.websphere.objectgrid.management
Interface PlacementMediationServiceMBean

public interface PlacementMediationServiceMBean

This MBean interface allows a client process to perform operations on and get status from the PlacementMediationService running in a dynamic environment. The object name pattern for this MBean is: 

 com.ibm.websphere.objectgrid:type=PlacementMediationService
If ObjectGrid is running in a WebSphere Application Server process, more key=value pairs may be added to the object name.

Since:
7.1, XC10

Method Summary
javax.management.openmbean.CompositeData dismissLink(java.lang.String foreignDomain)
          Dismiss a previously established link with the foreign domain specified.
javax.management.openmbean.CompositeData establishLink(java.lang.String foreignDomain, java.lang.String endPoints)
          Establish a link between this domain and the foreign domain specified.
javax.management.openmbean.TabularData getLinkedDomains()
          Retrieve the foreign domains that have an active link with the local domain.
 

Method Detail

establishLink

javax.management.openmbean.CompositeData establishLink(java.lang.String foreignDomain,
                                                       java.lang.String endPoints)

Establish a link between this domain and the foreign domain specified. This is functionally equivalent to providing the foreign domain and its end points in the server properties file at server startup time.

Domains that are linked will share placement with each other. When compatible map sets are detected within linked domains, a multi-primary topology will be achieved. Data written to a primary is either domain will be asynchronously replicated to the other domain.

The result is a CompositeData that includes the following items:
Item NameTypeDescription

Result
String
The result of the attempt.

StatusBefore
String
The status of the link before the attempt was made to establish the link.

StatusAfter
String
The status of the link after the attempt was made to establish the link.

Parameters:
foreignDomain - the name of the foreign domain
endPoints - end points of the foreign domain CatalogServerProperties.setDomainEndPoints(String, String)

dismissLink

javax.management.openmbean.CompositeData dismissLink(java.lang.String foreignDomain)

Dismiss a previously established link with the foreign domain specified. Any map sets that were participating in a multi-primary topology will be disconnected from each other. Data will no longer be replicated from between domains.

The result is a CompositeData that includes the following items:
Item NameTypeDescription

Result
String
The result of the attempt. Can be one of: SUCCESS, FAILURE, NOP

StatusBefore
String
The status of the link before the attempt was made to dismiss the link. Can be one of: LINKED, ESTABLISHING_LINK, UNLINKED, DISMISSING_LINK

StatusAfter
String
The status of the link after the attempt was made to dismiss the link. Can be one of: LINKED, ESTABLISHING_LINK, UNLINKED, DISMISSING_LINK

Parameters:
foreignDomain - the name of the foreign domain
Returns:
CompositeData representing the status of the attempt to dismiss the link with the foreign domain

getLinkedDomains

javax.management.openmbean.TabularData getLinkedDomains()

Retrieve the foreign domains that have an active link with the local domain.

The result is a TabularData where each row is a CompositeData that includes the following items:
Item NameTypeDescription

Domain
String
The name of the foreign domain linked to the local domain.

Returns:
TabularData representing the foreign domains linked to this domain


com.ibm.websphere.objectgrid.management
Interface PlacementServiceMBean

All Superinterfaces:
CoreGroupServiceMBean

public interface PlacementServiceMBean
extends CoreGroupServiceMBean

This MBean interface allows a client process to perform operations on and get status from the PlacementService running in a dynamic environment. The object name pattern for this MBean is: 

 com.ibm.websphere.objectgrid:type=PlacementService
If ObjectGrid is running in a WebSphere Application Server process, more key=value pairs may be added to the object name.

Since:
WAS XD 6.1 FIX3, XC10

Field Summary
static int ALL
          Constant representing a all shard types
static int ASYNCHRONOUS_REPLICA
          Constant representing an asynchronous replica shard type.
static int PRIMARY
          Constant representing a primary shard type.
static int SYNCHRONOUS_REPLICA
          Constant representing a synchronous replica shard type.
 
Fields inherited from interface com.ibm.websphere.objectgrid.management.CoreGroupServiceMBean

HEARTBEAT_FREQUENCY_LEVEL_AGGRESSIVE, HEARTBEAT_FREQUENCY_LEVEL_RELAXED, HEARTBEAT_FREQUENCY_LEVEL_TYPICAL, STATUS_QUORUM_DISABLED, STATUS_QUORUM_ENABLED_NORMAL, STATUS_QUORUM_ENABLED_WAITING, STATUS_QUORUM_INCONSISTENT, STATUS_QUORUM_OVERRIDE
 
Method Summary
java.lang.String balanceShardTypes(java.lang.String objectGridName, java.lang.String mapSetName)
          The placement service will examine the distribution of primaries and replicas for a given mapSet and attempt (if zone rules and other balancing constraints allow) to achieve a consistent primary to replica ratio across the set of containers.
java.lang.String balanceStatus(java.lang.String objectGridName, java.lang.String mapSetName)
          Check the balance status (suspended or resumed) for a specified MapSet.
java.lang.String collectContainerStatus(java.lang.String objectGridName, java.lang.String mapSetName)
          Retrieves the container status for all containers in the domain.
java.lang.String getCoreGroups()
          Gets the coregroup status.
java.lang.String getObjectGridNames()
          Gets the names of all ObjectGrids and their mapsets in the domain.
java.lang.String listCoreGroupMembers(java.lang.String coreGroupName)
          List the coregroup members for a given coregroup.
java.lang.String listObjectGridPlacement(java.lang.String objectGridName, java.lang.String mapSetName)
          List the placement of shards for each container in the domain.
java.lang.String listObjectGridPlacementStatus(java.lang.String objectGridName, java.lang.String mapSetName)
          List the current placement status.
java.lang.String listPartition(java.lang.String objectGridName, java.lang.String mapSetName, java.lang.String partitionId)
          List the partition placement status in the domain.
java.lang.String listShards(java.lang.String objectGridName, java.lang.String mapSetName, java.lang.String containerName, int mask)
          List the shard placement status.
java.lang.String listVerifiedRoutingTable(java.lang.String objectGridName)
          Calling this method will return an XML string of the current known routing table.
java.lang.String replaceLostShards(java.lang.String objectGridName, java.lang.String mapSetName)
          Lost shards are placed onto the UNREPAIRED container when autoReplaceLostShards is disabled.
java.lang.String resumeBalancing(java.lang.String objectGridName, java.lang.String mapSetName)
          Execute balancing operation at next opportunity and allow execution of future balancing attempts for the map set specified.
java.util.List retrieveAllServersJMXAddresses()
          Retrieves a List of JMX addresses for all servers that have registered with the placement service.
java.lang.String retrieveMapSetName(java.lang.String gridName, java.lang.String mapName)
          Retrieves the name of the MapSet in which the specified map is defined.
java.util.List retrieveServerJMXAddress(java.lang.String hostName, java.lang.String serverName)
          Retrieves a List of JMX address strings for a specific host and server name that has registered with the placement service.
java.lang.String suspendBalancing(java.lang.String objectGridName, java.lang.String mapSetName)
          Prevent future balancing attempts for a specific map set.
java.lang.String tearDownServers(java.lang.String[] servers)
          Each of the container servers that are passed into this method will be stopped.
java.lang.String triggerPlacement(java.lang.String objectGridName, java.lang.String mapSetName)
          Placement normally occurs implicitly after an event such as an ObjectGrid container starting or stopping.
 
Methods inherited from interface com.ibm.websphere.objectgrid.management.CoreGroupServiceMBean

getHeartBeatFrequencyLevel, getQuorumActivationStatus, overrideQuorum, setHeartBeatFrequencyLevel
 

Field Detail

PRIMARY

static final int PRIMARY

Constant representing a primary shard type.

SYNCHRONOUS_REPLICA

static final int SYNCHRONOUS_REPLICA

Constant representing a synchronous replica shard type.

ASYNCHRONOUS_REPLICA

static final int ASYNCHRONOUS_REPLICA

Constant representing an asynchronous replica shard type.

ALL

static final int ALL

Constant representing a all shard types

Method Detail

retrieveServerJMXAddress

java.util.List retrieveServerJMXAddress(java.lang.String hostName,
                                        java.lang.String serverName)

Retrieves a List of JMX address strings for a specific host and server name that has registered with the placement service.

Parameters:
hostName - The name of the host to retrieve the JMX addresses.
serverName - The name of the server to retrieve the JMX addresses.
Returns:
the List of all JMX address strings for the specified host and server name.

retrieveAllServersJMXAddresses

java.util.List retrieveAllServersJMXAddresses()

Retrieves a List of JMX addresses for all servers that have registered with the placement service.

Returns:
the List of all servers' JMX addresses

collectContainerStatus

java.lang.String collectContainerStatus(java.lang.String objectGridName,
                                        java.lang.String mapSetName)

Retrieves the container status for all containers in the domain.

The results are returned in the following format: 

 <container name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>">
   <shard type="<type>" partitionName="<partition>"/>
 </container>

Parameters:
objectGridName - The name of the ObjectGrid for which to get container status.
mapSetName - The name of the mapset for which to get the container status.
Returns:
The String status object for all containers in XML form.

listObjectGridPlacement

java.lang.String listObjectGridPlacement(java.lang.String objectGridName,
                                         java.lang.String mapSetName)

List the placement of shards for each container in the domain.

The results are returned in the following format: 

 <objectGrid name="<objectgrid>" mapSetName="<mapset">
   <container name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>">
      <shard type="<type>" partitionName="<partition>" reserved="<true>"/>
   /container>
 </objectGrid>
NOTE: The default value for the "reserved" attribute is false.

Parameters:
objectGridName - The name of the ObjectGrid for which to get placement status.
mapSetName - The name of the mapset for which to get the placement status.
Returns:
The placement status in XML form.

listObjectGridPlacementStatus

java.lang.String listObjectGridPlacementStatus(java.lang.String objectGridName,
                                               java.lang.String mapSetName)

List the current placement status.

The results are returned in the following format: 

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <configuration>
     <attribute name="<placementStrategy>" value="<strategy>"/>
     <attribute name="<numInitialContainers>" value="<num>"/>
     <attribute name="<minSyncReplicas>" value="<min>"/>
     <attribute name="<developmentMode>" value="<mode>"/>
   </configuration>
   <runtime>
     <attribute name="<numContainers>" value="<num>"/>
     <attribute name="<numMachines>" value="<num>"/>
     <attribute name="<numOutstandingWorkItems>" value="<num>"/>
     <attribute name="<numActiveZones>" value="<num>"/>
   </runtime>
 </objectGrid>

Parameters:
objectGridName - The name of the ObjectGrid for which to get placement status.
mapSetName - The name of the mapset for which to get the placement status.
Returns:
The placement status in XML form.

getCoreGroups

java.lang.String getCoreGroups()

Gets the coregroup status.

The results are returned in the following format: 

 <coreGroup name="<coregroup>">
   <coreGroupLeader hostName="<host>" serverName="<server>"/>
   <coreGroupMember hostName="<host>" serverName="<server>"/>
 </coreGroup>

Returns:
the coregroup status in XML form.

listCoreGroupMembers

java.lang.String listCoreGroupMembers(java.lang.String coreGroupName)

List the coregroup members for a given coregroup.

The results are returned in the following format: 

 <coreGroup name="<coregroup>">
   <coreGroupMember hostName="<host>" serverName="<server>"/>
 </coreGroup>

Parameters:
coreGroupName - The name of the coregroup for which to get the members.
Returns:
The coregroup members in XML form.

listPartition

java.lang.String listPartition(java.lang.String objectGridName,
                               java.lang.String mapSetName,
                               java.lang.String partitionId)

List the partition placement status in the domain. The results are returned in the following format: 

 <partition name="<partition>">
   <shard type="<type>" containerName="<container>" hostName="<host>" serverName="<server>"/>
 </partition>

Parameters:
objectGridName - The name of the ObjectGrid for which to get placement status.
mapSetName - The name of the mapset for which to get the placement status.
partitionId - The name of the partition for which to get the placement status.
Returns:
The partition placement status in the XML form.

listShards

java.lang.String listShards(java.lang.String objectGridName,
                            java.lang.String mapSetName,
                            java.lang.String containerName,
                            int mask)

List the shard placement status.

The results are returned in the following format: 

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <container name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>">
     <shard type="<type>" partitionName="<partition>"/>
   </container>
 </objectGrid>

Parameters:
objectGridName - The name of the ObjectGrid for which to get placement status.
mapSetName - The name of the mapset for which to get the placement status.
containerName - The name of the container for which to get the placement status. If empty string ( "" ), get shard placement for all containers.
mask - The Integer mask to determine for which shard types to get status. PRIMARY, SYNCHRONOUS_REPLICA, ASYNCHRONOUS_REPLICA

getObjectGridNames

java.lang.String getObjectGridNames()

Gets the names of all ObjectGrids and their mapsets in the domain.

The results are returned in the following format: 

 <objectGrid name="<objectgrid>" mapSetName="<mapset>"/>

Returns:
the names of all ObjectGrids and their mapsets in the domain in XML form.

replaceLostShards

java.lang.String replaceLostShards(java.lang.String objectGridName,
                                   java.lang.String mapSetName)

Lost shards are placed onto the UNREPAIRED container when autoReplaceLostShards is disabled. Shards on the UNREPAIRED will not be placed until this method is called.

Calling this method will move shards off the UNREPAIRED container onto the UNASSIGNED container.

Balance and placement operations will be queued up for the MapSet specified. These operations will execute when all outstanding placement work from previous events has completed.

The string returned is an XML representation of the shards that moved as a result of the call to this method. 

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <shard type="<type>" partitionName="<partition>">
     <currentContainer name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>"/>
     <previousContainer name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>"/>
   </shard>
 </objectGrid>

The returned XML will look as follows when no shards have been moved: 

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <!-- No shards were moved -->
 </objectGrid>

Parameters:
objectGridName - replace lost shards for this ObjectGrid
mapSetName - replace lost shards for this MapSet
Returns:
An XML String containing shards that have moved
Since:
WAS XD 6.1.0.5

triggerPlacement

java.lang.String triggerPlacement(java.lang.String objectGridName,
                                  java.lang.String mapSetName)

Placement normally occurs implicitly after an event such as an ObjectGrid container starting or stopping.

Calling this method will trigger a placement operation for the ObjectGrid and MapSet specified.

Under normal circumstances, the numInitialContainers attribute (in the deployment policy) must be met in order for placement to occur. However, when this method is called, the numInitialContainers value is ignored.

The string returned is an XML representation of the shards that moved as a result of the call to this method. 

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <shard type="<type>" partitionName="<partition>">
     <currentContainer name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>"/>
     <previousContainer name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>"/>
   </shard>
 </objectGrid>

The returned XML will look as follows when no shards have been moved: 

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <!-- No shards were moved -->
 </objectGrid>

Parameters:
objectGridName - trigger placement for this ObjectGrid
mapSetName - trigger placement for this MapSet
Returns:
An XML String containing shards that have moved
Since:
WAS XD 6.1.0.5
MapSet.setNumInitialContainers(int)

tearDownServers

java.lang.String tearDownServers(java.lang.String[] servers)

Each of the container servers that are passed into this method will be stopped. If the server cannot be reached, all of the server's artifacts will be removed.

Use this method if servers are found to be in a corrupt state or bindings need to be cleared from the catalog server.

The string returned is an XML representation of the results of the attempt to tear down each of the servers. If the command is successful, the XML will look as follows: 

 <domain name="<domain>">
   <server name="<server>" tearDownSuccessful="true"/>
   <server name="<server>" tearDownSuccessful="true"/>
 </domain>
If the command is not successful, the string will look as follows (where the exception element is only present if an exception is part of the failure): 

 <domain name="<domain>">
   <server name="<server>" tearDownSuccessful="false" reason="<String>">
       <exception type="<String>" message="<String>" stack="<String>"/>
   </server>
 </domain>

Parameters:
servers - String array of servers to tear down.
Returns:
An XML String containing the results of tear down attempts.
Since:
WAS XD 6.1.0.5 FIX2

listVerifiedRoutingTable

java.lang.String listVerifiedRoutingTable(java.lang.String objectGridName)

Calling this method will return an XML string of the current known routing table. The Placement service will contact each shard and return state on whether it was able to verify that's shard's existence. All shards will be included in the XML doc, whether they were reachable or not. The user can use the reachable attribute below to filter valid or invalid shards. 

 <objectGrid name="<objectgrid>" name="<name>">
   <primary zone="<zone>"> partition="<partition>"> state="<reachable>"> ipaddress="<ipaddress>">
     <replica zone="<zone>"> partition="<partition>"> state="<reachable>"> ipaddress="<ipaddress>">
   </primary>
 </objectGrid>

Parameters:
objectGridName - retrieve routing table for this ObjectGrid
Returns:
An XML String containing a pre-verified routing table
Since:
WAS XD 6.1.0.5 FIX2

retrieveMapSetName

java.lang.String retrieveMapSetName(java.lang.String gridName,
                                    java.lang.String mapName)

Retrieves the name of the MapSet in which the specified map is defined.

Parameters:
gridName - the name of the ObjectGrid
mapName - the name of the map
Returns:
the name of the MapSet in which the specified map is defined.
Since:
7.0

balanceShardTypes

java.lang.String balanceShardTypes(java.lang.String objectGridName,
                                   java.lang.String mapSetName)

The placement service will examine the distribution of primaries and replicas for a given mapSet and attempt (if zone rules and other balancing constraints allow) to achieve a consistent primary to replica ratio across the set of containers.

If the number of primaries or the number of replicas do not divide evenly across the containers, some tolerance must be allowed for the ratio to differ from container to container. However, the difference in the number of primaries from one container to the next will not be greater than 1. Similarly, the difference in the number of replicas from one container to the next will not be greater than 1.

Null arguments are not allowed as input to this method.

The results are returned in the following format: 

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <shard type="<type>" partitionName="<partition>">
     <currentContainer name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>"/>
     <previousContainer name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>"/>
   </shard>
 </objectGrid>
If no shards were moved or a problem was encountered attempting to execute this method, no shard elements will appear in the XML output. A detail element will appear instead. The message attribute will have further information. 

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <detail message="<message>" />
 </objectGrid>

Parameters:
objectGridName - the grid
mapSetName - the map set within the grid
Returns:
An XML String containing the results of the attempt to redistribute shards for better primary/replica balance
Since:
7.1.1

suspendBalancing

java.lang.String suspendBalancing(java.lang.String objectGridName,
                                  java.lang.String mapSetName)

Prevent future balancing attempts for a specific map set. Balancing work that is in progress will be allowed to complete.

Other placement activities are allowed to execute while balancing is suspended.

  • shard promotion due to container loss
  • shard role swap
  • shard reservation
  • triggerPlacement
  • replaceLostShards

Balancing will remain suspended until it is resumed by calling resumeBalancing(String, String).

Null arguments are not allowed as input to this method.

The results are returned in the following format: 

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <suspendBalancing currentValue="<currentValue>" previousValue="<previousValue>"/>
 </objectGrid>

Additionally, an optional detail element may be contained within the suspendBalancing element. The detail element will include additional data regarding execution of this method. The XML result will be in the following format when a detail element is included: 

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <suspendBalancing currentValue="<currentValue>" previousValue="<previousValue>">
     <detail message="<message>" />
   <suspendBalancing/>
 </objectGrid>

Parameters:
objectGridName - suspend balancing for the map set specified within this ObjectGrid
mapSetName - suspend balancing for this map set
Returns:
An XML String containing the results of the attempt to suspend balancing
Since:
7.1.0.3

resumeBalancing

java.lang.String resumeBalancing(java.lang.String objectGridName,
                                 java.lang.String mapSetName)

Execute balancing operation at next opportunity and allow execution of future balancing attempts for the map set specified. Balancing is executed in reaction to key placement events. Such events include containers starting and containers stopping.

By default, balancing work is executed unless suspendBalancing(String, String) has been called for the map set.

Null arguments are not allowed as input to this method.

The results are returned in the following format: 

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <suspendBalancing currentValue="<currentValue>" previousValue="<previousValue>"/>
 </objectGrid>

Additionally, an optional detail element may be contained within the suspendBalancing element. The detail element will include additional data regarding execution of this method. The XML result will be in the following format when a detail element is included: 

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <suspendBalancing currentValue="<currentValue>" previousValue="<previousValue>">
     <detail message="<message>" />
   <suspendBalancing/>
 </objectGrid>

Parameters:
objectGridName - resume balancing for the map set specified within this ObjectGrid
mapSetName - resume balancing for this map set
Returns:
An XML String containing the results of the attempt to resume balancing
Since:
7.1.0.3

balanceStatus

java.lang.String balanceStatus(java.lang.String objectGridName,
                               java.lang.String mapSetName)

Check the balance status (suspended or resumed) for a specified MapSet.

Null arguments are not allowed as input to this method.

The string returned is an XML representation of the balance status. The XML will look as follows: 

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <balanceStatus suspended="<suspended>" />
 </objectGrid>

Additionally, an optional detail element may be contained within the balanceStatus element. When balancing has been pre-suspended, the message attribute of the detail element will contain the following message. 

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <balanceStatus suspended="true" >
     <detail message="Balancing has been pre-suspended for this mapSet." />
   </balanceStatus>
 </objectGrid>

Parameters:
objectGridName - check balance status for the map set specified within this ObjectGrid
mapSetName - check balance status for this map set
Returns:
An XML String containing the balance status
Since:
7.1.1
resumeBalancing(String, String)


com.ibm.websphere.objectgrid.management
Interface QueryManagerMBean

public interface QueryManagerMBean

This MBean interface allows a client process to perform operations on and get status from an ObjectGrid Query Manager running in a dynamic environment. The object name pattern for this MBean is: 

 com.ibm.websphere.objectgrid:type=QueryManager,name=<grid name>,mapset=<mapset name>,partition=<partition number>,host=<host>,ogServerName=<server>
If ObjectGrid is running in a WebSphere Application Server process, more key=value pairs may be added to the object name.

Since:
WAS XD 6.1.0.5, XC10

Method Summary
double getPlanCreationTime(java.lang.String query)
          Gets the query's plan creation time attribute loaded up by the retrieveStatsModule() method.
double getQueryExecutionCount(java.lang.String query)
          Gets the query's execution count attribute loaded up by the retrieveStatsModule() method.
double getQueryExecutionTime(java.lang.String query)
          Gets the query's execution time attribute loaded up by the retrieveStatsModule() method.
double getQueryFailureCount(java.lang.String query)
          Gets the query's failure count attribute loaded up by the retrieveStatsModule() method.
double getQueryResultCount(java.lang.String query)
          Gets the query's result count attribute loaded up by the retrieveStatsModule() method.
QueryStatsModule retrieveStatsModule(java.lang.String query)
          Gets the QueryStatsModule used to retrieve statistics associated with the specified query String
 

Method Detail

getPlanCreationTime

double getPlanCreationTime(java.lang.String query)

Gets the query's plan creation time attribute loaded up by the retrieveStatsModule() method.

QueryStatsModule.getPlanCreationTime(boolean copy)

getQueryExecutionTime

double getQueryExecutionTime(java.lang.String query)

Gets the query's execution time attribute loaded up by the retrieveStatsModule() method.

QueryStatsModule.getQueryExecutionTime(boolean copy)

getQueryExecutionCount

double getQueryExecutionCount(java.lang.String query)

Gets the query's execution count attribute loaded up by the retrieveStatsModule() method.

QueryStatsModule.getQueryExecutionCount(boolean copy)

getQueryResultCount

double getQueryResultCount(java.lang.String query)

Gets the query's result count attribute loaded up by the retrieveStatsModule() method.

QueryStatsModule.getQueryResultCount(boolean copy)

getQueryFailureCount

double getQueryFailureCount(java.lang.String query)

Gets the query's failure count attribute loaded up by the retrieveStatsModule() method.

QueryStatsModule.getQueryFailureCount(boolean copy)

retrieveStatsModule

QueryStatsModule retrieveStatsModule(java.lang.String query)

Gets the QueryStatsModule used to retrieve statistics associated with the specified query String

Returns:
an QueryStatsModule for statistics associated with the specified query String


com.ibm.websphere.objectgrid.management
Interface QuorumManagerMBean

public interface QuorumManagerMBean

Each catalog service has a QuorumManager and an associated MBean. The QuorumManager monitors and manages the quorum state of the catalog service grid. When quorum is enabled, the QuorumManager for each catalog service process detects when all catalog services in the grid have quorum or not. This MBean allows querying the current quorum state and allows administrators to force quorum when there is a network failure. 

 com.ibm.websphere.objectgrid:type=QuorumManager
If ObjectGrid is running in a WebSphere Application Server process, more key=value pairs may be added to the object name.

Since:
7.0, XC10

Method Summary
java.lang.String[] getActiveCatalogServerNames()
          Retrieves the names of the known active catalog service processes.
int getActiveCatalogServers()
          Retrieve the known number of active catalog service processes.
int getQuorumCatalogServers()
          Retrieve the number of catalog service processes required for quorum.
void overrideQuorum()
          This operation forces surviving catalog service grid processes to reestablish a quorum.
 

Method Detail

overrideQuorum

void overrideQuorum()
                    throws java.lang.Exception

This operation forces surviving catalog service grid processes to reestablish a quorum.

If a portion the catalog service grid fails or is divided due to a network failure, the grid will lose quorum. Once the administrator identifies the failure and the viable portion of the grid, this operation can be invoked on any of the surviving catalog service processes to reestablish a quorum. Reestablishing a quorum will allow the catalog service to continue to react to failures and topology changes.

Throws:
java.lang.Exception

getActiveCatalogServers

int getActiveCatalogServers()

Retrieve the known number of active catalog service processes.

Returns:
the known number of active catalog service processes.

getQuorumCatalogServers

int getQuorumCatalogServers()

Retrieve the number of catalog service processes required for quorum.

Returns:
the number of catalog service processes required for quorum.

getActiveCatalogServerNames

java.lang.String[] getActiveCatalogServerNames()

Retrieves the names of the known active catalog service processes.

Returns:
the names of the known active catalog service processes.
Since:
7.1


com.ibm.websphere.objectgrid.management
Interface ServerMBean

All Known Subinterfaces:
DynamicServerMBean

public interface ServerMBean

This MBean interface allows a client process to access different attributes about a specific server process.

Since:
WAS XD 6.0.1, XC10

Method Summary
java.lang.String getServerName()
          Gets the name of the server associated with this MBean.
void modifyServerTraceSpec(java.lang.String spec)
          Deprecated. This is deprecated in version 7.1. See DynamicServerMBean.setTraceSpec(String)
boolean stopServer()
          Stops the server associated with this MBean.
 

Method Detail

getServerName

java.lang.String getServerName()

Gets the name of the server associated with this MBean.

Returns:
the server name

stopServer

boolean stopServer()

Stops the server associated with this MBean.

Returns:
true if server was stopped,

modifyServerTraceSpec

void modifyServerTraceSpec(java.lang.String spec)

Deprecated. This is deprecated in version 7.1. See DynamicServerMBean.setTraceSpec(String)

Modifies the trace spec for the server associated with this MBean.


com.ibm.websphere.objectgrid.management
Interface SessionMBean

public interface SessionMBean

This MBean interface allows a client process to access different attributes and statistical data about a specific session. The object name pattern for this MBean is: 

 com.ibm.websphere.objectgrid:type=Session,name=<id>,host=<host>,ogServerName=<server>
If ObjectGrid is running in a WebSphere Application Server process, more key=value pairs may be added to the object name.

Since:
WAS XD 6.0.1, XC10

Method Summary
long getAccessedSessionsCount()
          Gets acessed sessions count
long getAccessToNonExistentSessionCount()
          Gets access to non-existent session count
long getActiveSessionsCount()
          Gets active sessions count
long getAffinityBreaksCount()
          Gets affinity breaks count
long getCacheDiscardsCount()
          Gets cache discards count
long getCreatedSessionsCount()
          Gets the map count attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.
long getInvalidatedByTimeoutCount()
          Gets invalidated by timeout count
long getInvalidatedSessionsCount()
          Gets invalidated sessions count
long getMemoryCount()
          Gets memory count
java.lang.String getSessionID()
          Gets the ID of the session instance associated with this MBean.
java.lang.String getSessionStatsModule()
          Gets a string representation of the SessionStatsModule attributes loaded up by the retrieveStatsModule() method.
SessionStatsModule retrieveStatsModule()
          Gets the SessionStatsModule used to retrieve statistics associated with the session for this MBean.
 

Method Detail

retrieveStatsModule

SessionStatsModule retrieveStatsModule()

Gets the SessionStatsModule used to retrieve statistics associated with the session for this MBean.

getSessionID

java.lang.String getSessionID()

Gets the ID of the session instance associated with this MBean.

Returns:
the ID of the session instance associated with this MBean.

getSessionStatsModule

java.lang.String getSessionStatsModule()

Gets a string representation of the SessionStatsModule attributes loaded up by the retrieveStatsModule() method.

SessionStatsModule

getCreatedSessionsCount

long getCreatedSessionsCount()

Gets the map count attribute loaded up by the retrieveStatsModule() or refreshStatsModule() method.

MapStatsModule.getNumEntries(boolean)

getInvalidatedSessionsCount

long getInvalidatedSessionsCount()

Gets invalidated sessions count

Returns:
the count of invalidated Sessions

getActiveSessionsCount

long getActiveSessionsCount()

Gets active sessions count

Returns:
the count of active Sessions

getMemoryCount

long getMemoryCount()

Gets memory count

Returns:
memory count

getCacheDiscardsCount

long getCacheDiscardsCount()

Gets cache discards count

Returns:
cache discards count

getAffinityBreaksCount

long getAffinityBreaksCount()

Gets affinity breaks count

Returns:
affinity breaks count

getInvalidatedByTimeoutCount

long getInvalidatedByTimeoutCount()

Gets invalidated by timeout count

Returns:
count

getAccessToNonExistentSessionCount

long getAccessToNonExistentSessionCount()

Gets access to non-existent session count

Returns:
count

getAccessedSessionsCount

long getAccessedSessionsCount()

Gets acessed sessions count

Returns:
count


com.ibm.websphere.objectgrid.management
Interface ShardMBean

public interface ShardMBean

This MBean interface allows a client process to perform operations on and get status from a shard running in a dynamic environment. The object name pattern for this MBean is: 

 com.ibm.websphere.objectgrid:type=Shard,name=<objectgrid>,objectgrid=<objectgrid>,mapset=<mapset>,partition=<partition id>,container=<container>,host=<host>,ogServerName=<server>
If ObjectGrid is running in a WebSphere Application Server process, more key=value pairs may be added to the object name.

Since:
WAS XD 6.1 FIX3, XC10

Field Summary
static java.lang.String ROLE_SWAP_REQUESTED_WITH_SAME_TYPE
          Indicates that this shard is the same type of shard as the requested swap type.
static java.lang.String ROLE_SWAP_SUCCESSFUL
          Indicates that the role swap was executed successfully.
static java.lang.String ROLE_SWAP_TIMEOUT
          Indicates that this shard has timed out waiting to inherit its requested role
static java.lang.String TYPE_INACTIVE
          Indicates the shard type is the inactive role.
static java.lang.String TYPE_PRIMARY
          Indicates the shard type is the primary role.
static java.lang.String TYPE_REPLICA_ASYNCHRONOUS
          Indicates the shard type is the asynchronous replica role.
static java.lang.String TYPE_REPLICA_SYNCHRONOUS
          Indicates the shard type is the synchronous replica role.
 
Method Summary
long getActiveRequestCount()
          Retrieves the number of requests currently being processed by this shard.
java.lang.String getContainerName()
          Retrieves the name of the container that is hosting this shard.
java.lang.String getDomainName()
          Retrieve the name of the catalog server grouping administering this shard.
long getForwardedRequestCount()
          Retrieves the number of requests that this shard has forwarded since its inception.
java.lang.String getMapSetName()
          Retrieve the name of the MapSet in which the shard resides.
java.lang.String getObjectGridName()
          Retrieve the name of the ObjectGrid in which the shard resides.
java.lang.String getPartitionName()
          Retreive the name of the partition in which the shard resides.
long getProcessedRequestCount()
          Retrieves the number of requests that this shard has processed since its inception.
java.lang.String getState()
          Retrieve the state of the shard.
long getTotalRequestCount()
          Retrieves the number of requests that this shard has processed or forwarded since its inception.
java.lang.String getType()
          Retrieve the type of the shard.
java.lang.String swapWithPrimary()
          Causes this shard to swap roles with the primary shard for the partition.
 

Field Detail

ROLE_SWAP_SUCCESSFUL

static final java.lang.String ROLE_SWAP_SUCCESSFUL

Indicates that the role swap was executed successfully.

Since:
7.1.0.0 FIX1
Constant Field Values

ROLE_SWAP_REQUESTED_WITH_SAME_TYPE

static final java.lang.String ROLE_SWAP_REQUESTED_WITH_SAME_TYPE

Indicates that this shard is the same type of shard as the requested swap type. No swap will be executed.

Since:
7.1.0.0 FIX1
Constant Field Values

ROLE_SWAP_TIMEOUT

static final java.lang.String ROLE_SWAP_TIMEOUT

Indicates that this shard has timed out waiting to inherit its requested role

Since:
7.1.0.0 FIX1
Constant Field Values

TYPE_PRIMARY

static final java.lang.String TYPE_PRIMARY

Indicates the shard type is the primary role. This means that this is the shard that handles all updates and coordinates state transitions with the replicas.

TYPE_REPLICA_SYNCHRONOUS

static final java.lang.String TYPE_REPLICA_SYNCHRONOUS

Indicates the shard type is the synchronous replica role. This means that this shard is receiving state updates from another shard that is acting as primary.

TYPE_REPLICA_ASYNCHRONOUS

static final java.lang.String TYPE_REPLICA_ASYNCHRONOUS

Indicates the shard type is the asynchronous replica role. This means that this shard is receiving state updates from another shard that is acting as primary.

TYPE_INACTIVE

static final java.lang.String TYPE_INACTIVE

Indicates the shard type is the inactive role. This means that this shard is not actively enrolled in the partition.

Method Detail

getObjectGridName

java.lang.String getObjectGridName()

Retrieve the name of the ObjectGrid in which the shard resides.

Returns:
The ObjectGrid name.

getMapSetName

java.lang.String getMapSetName()

Retrieve the name of the MapSet in which the shard resides.

Returns:
The MapSet name.

getPartitionName

java.lang.String getPartitionName()

Retreive the name of the partition in which the shard resides.

Returns:
The partition name.

getType

java.lang.String getType()

Retrieve the type of the shard.

Returns:
The shard type.

getDomainName

java.lang.String getDomainName()

Retrieve the name of the catalog server grouping administering this shard.

Returns:
The domain name.

getState

java.lang.String getState()

Retrieve the state of the shard.

Returns:
The shard state.

getTotalRequestCount

long getTotalRequestCount()

Retrieves the number of requests that this shard has processed or forwarded since its inception.

Returns:
A count of the total number of requests.

getActiveRequestCount

long getActiveRequestCount()

Retrieves the number of requests currently being processed by this shard.

Returns:
A count of the active requests.

getForwardedRequestCount

long getForwardedRequestCount()

Retrieves the number of requests that this shard has forwarded since its inception.

Returns:
A count of the total number of forwarded requests.

getProcessedRequestCount

long getProcessedRequestCount()

Retrieves the number of requests that this shard has processed since its inception.

Returns:
A count of the total number of processed requests.

getContainerName

java.lang.String getContainerName()

Retrieves the name of the container that is hosting this shard.

Returns:
The name of the container.
Since:
WAS XD 6.1.0.3

swapWithPrimary

java.lang.String swapWithPrimary()

Causes this shard to swap roles with the primary shard for the partition. This shard becomes the primary while the shard that was previously the primary inherits this shard's former role.

If the role swap is not complete within 10 seconds, this operation will timeout.

Returns:
String the contains the return code of the operation
Since:
7.1.0.0 FIX1
ROLE_SWAP_REQUESTED_WITH_SAME_TYPE, ROLE_SWAP_TIMEOUT


com.ibm.websphere.objectgrid.management
Interface ThreadPoolMBean

public interface ThreadPoolMBean

This MBean interface allows user to access the thread pool properties. The object name pattern for this MBean is: 

 com.ibm.websphere.objectgrid:type=ThreadPool
If ObjectGrid is running in a WebSphere Application Server process, more key=value pairs may be added to the object name.

Since:
7.0.0.0 FIX2, XC10

Method Summary
int getActiveThreadCount()
          Retrieves the approximate number of active threads in the pool.
int getMaximumSize()
          Retrieves the maximum number of threads in the pool.
int getMinimumSize()
          Retrieves the minimum number of threads in the pool.
java.lang.String getName()
          Retrieves the name of the ThreadPool.
void setMaximumSize(int size)
          Sets the maximum thread pool size.
void setMinimumSize(int size)
          Sets the minimum thread pool size.
 

Method Detail

setMaximumSize

void setMaximumSize(int size)

Sets the maximum thread pool size.

Parameters:
size - the maximum number of threads.

getMaximumSize

int getMaximumSize()

Retrieves the maximum number of threads in the pool.

Returns:
the maximum number of threads in the pool

setMinimumSize

void setMinimumSize(int size)

Sets the minimum thread pool size.

Parameters:
size - the minimum number of threads.

getMinimumSize

int getMinimumSize()

Retrieves the minimum number of threads in the pool.

Returns:
the minimum number of threads in the pool

getActiveThreadCount

int getActiveThreadCount()

Retrieves the approximate number of active threads in the pool.

Returns:
the number of active threads in the pool in use

getName

java.lang.String getName()

Retrieves the name of the ThreadPool.

Returns:
the name of the ThreadPool


com.ibm.websphere.objectgrid
Class AvailabilityState

java.lang.Object
  com.ibm.websphere.objectgrid.AvailabilityState

All Implemented Interfaces:
java.io.Serializable

public final class AvailabilityState
extends java.lang.Object
implements java.io.Serializable

Each shard in a distributed ObjectGrid has an availability state associated with it. This state refers to the shard's ability to process incoming requests.

Since:
WAS XD 6.1.0.3, XC10

Field Summary
static AvailabilityState OFFLINE
          An AvailabilityState.OFFLINE indicates that a shard is offline and unable to process requests.
static AvailabilityState ONLINE
          An AvailabilityState.ONLINE indicates that a shard is online.
static AvailabilityState PRELOAD
          An AvailabilityState.PRELOAD indicates that a shard is in the preload state.
static AvailabilityState QUIESCE
          An AvailabilityState.QUIESCE indicates that a shard is in quiesce.
static AvailabilityState UNKNOWN
          An AvailabilityState.UNKNOWN indicates that the availability state of the shard could not be determined.
 
Method Summary
int getId()
          Returns the internal identifier for this state.
java.lang.String toString()
           
 
Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

OFFLINE

public static final AvailabilityState OFFLINE

An AvailabilityState.OFFLINE indicates that a shard is offline and unable to process requests.

PRELOAD

public static final AvailabilityState PRELOAD

An AvailabilityState.PRELOAD indicates that a shard is in the preload state. When in the preload state, a shard will reject all requests that are not initiated from a client that is preloading data into the ObjectGrid.

ONLINE

public static final AvailabilityState ONLINE

An AvailabilityState.ONLINE indicates that a shard is online. A shard that is online is available for processing requests.

QUIESCE

public static final AvailabilityState QUIESCE

An AvailabilityState.QUIESCE indicates that a shard is in quiesce. Quiesce is a transitional state. Shards that are in the quiesce state are on their way to being offline. A shard in the quiesce state will allow all pending transactions to complete before moving to the AvailabilityState.OFFLINE, assuming that all pending transactions complete within 30 seconds after entering the quiesce state.

UNKNOWN

public static final AvailabilityState UNKNOWN

An AvailabilityState.UNKNOWN indicates that the availability state of the shard could not be determined.

Method Detail

getId

public int getId()

Returns the internal identifier for this state.

Returns:
the internal id.
Since:
7.1.1

toString

public java.lang.String toString()

Overrides:
toString in class java.lang.Object


com.ibm.websphere.objectgrid
Interface BackingMap

All Superinterfaces:
ClientReplicableMap

public interface BackingMap
extends ClientReplicableMap

This is the public interface to the BackingMap. It is returned when a new Map is defined on the ObjectGrid. It allows the Map to be customized with various plug-ins or by setting properties. The defaults are:

  • No external Evictor, but an internal time-based evictor is provided by default
  • No Loader
  • No EventListeners
  • No MapIndexPlugins
  • An internal ObjectTransformer
  • An internal OptimisticCallback
  • Key is not copied
  • A value CopyMode of CopyMode.COPY_ON_READ_AND_COMMIT
  • A LockStrategy of LockStrategy.OPTIMISTIC
  • A default lock timeout
  • null values are supported
  • A default number of buckets
  • A default number of lock buckets
  • Synchronous preload
  • Read/write map by default
  • A TimeToLive of 0 (indicating unlimited time)
  • A TtlEvictor type of TTLType.NONE
  • Write-behind updates is disabled
  • Time-based database updates are disabled
  • Eviction triggers are not set

Since:
WAS XD 6.0, XC10

Nested Class Summary
 
Nested classes/interfaces inherited from interface com.ibm.websphere.objectgrid.ClientReplicableMap

ClientReplicableMap.Mode
 
Field Summary
static int CLIENT
          Constant used to indicate this map is a client to a server map
static int DEFAULT_LOCK_TIMEOUT
          Default lock timeout used if setLockTimeout(int) is not invoked.
static int DEFAULT_NUMBER_OF_BUCKETS
          Default number of lock buckets used if setNumberOfBuckets(int) is not invoked.
static int DEFAULT_NUMBER_OF_LOCK_BUCKETS
          Default number of lock buckets used if setNumberOfLockBuckets(int) is not invoked.
static java.lang.String EVICTIONTRIGGER_MEMORY_USAGE_THRESHOLD
          The eviction trigger string constant to enable memory based eviction using memory usage threshold provided by the java.lang.management.MemoryPoolMXBean.
static int LOCAL
          Constant used to indicate this map is not a distributed map.
static int SERVER
          Constant used to indicate this map is a server map.
 
Fields inherited from interface com.ibm.websphere.objectgrid.ClientReplicableMap

CONTINUOUS_REPLICATION, NONE, SNAPSHOT_REPLICATION
 
Method Summary
void addMapEventListener(EventListener eventListener)
          Adds an EventListener to this BackingMap.
void addMapEventListener(MapEventListener eventListener)
          Deprecated. This method is deprecated in version 7.1.1, use the addMapEventListener(EventListener) method.
void addMapIndexPlugin(MapIndexPlugin index)
          Adds an MapIndexPlugin to this Map.
void createDynamicIndex(MapIndexPlugin index, DynamicIndexCallback dynamicIndexCallback)
          Creates a dynamic index on the BackingMap.
void createDynamicIndex(java.lang.String name, boolean isRangeIndex, java.lang.String attributeName, DynamicIndexCallback dynamicIndexCallback)
          Creates a dynamic index on the BackingMap.
boolean getCopyKey()
          Gets whether keys are copied for this BackingMap.
CopyMode getCopyMode()
          Gets the CopyMode being used by this BackingMap.
EntityMetadata getEntityMetadata()
          Retreive the metadata for the entity associated with this backing map.
java.lang.String getEvictionTriggers()
          Returns the types of additional eviction triggers.
Evictor getEvictor()
          Gets the Evictor being used by this BackingMap.
Loader getLoader()
          Gets the Loader being used by this BackingMap.
LockStrategy getLockStrategy()
          Gets the LockStrategy object being used by this BackingMap.
int getLockTimeout()
          Gets the lock timeout value used by the lock manager for this BackingMap.
java.util.List getMapEventListeners()
          Gets the current list of EventListeners.
java.util.List getMapIndexPlugins()
          Returns the current list of MapIndexPlugin objects for this BackingMap.
java.lang.String getMapSetName()
          Retrieves the name of the MapSet that this BackingMap is currently associated with.
int getMapType()
          Returns the type of BackingMap.
java.lang.String getName()
          Gets the name of the BackingMap.
boolean getNullValuesSupported()
          Gets whether this BackingMap supports null values or not.
int getNumberOfBuckets()
          Gets the number of buckets defined for this BackingMap.
int getNumberOfLockBuckets()
          Gets the number of lock buckets defined for the hash map used by lock manager for this backing map.
ObjectGrid getObjectGrid()
          Gets the ObjectGrid that owns this BackingMap.
ObjectTransformer getObjectTransformer()
          Gets the ObjectTransformer object being used by this BackingMap and/or Loader.
OptimisticCallback getOptimisticCallback()
          Gets the OptimisticCallback being used by this BackingMap and/or Loader or null if the LockStrategy is not optimistic.
int getPartitionId()
          Gets the partition identifier being used by this BackingMap.
PartitionManager getPartitionManager()
          Allows access to the PartitionManager that is defined for this BackingMap.
boolean getPreLoadMode()
          Returns whether this BackingMap will be asynchronously preloaded or not if a Loader is set.
boolean getReadOnly()
          Retrieves the map type.
com.ibm.websphere.objectgrid.plugins.io.SerializerAccessor getSerializerAccessor()
          Retrieve the SerializerAccessor for this map.
BackingMapLifecycleListener.State getState()
          Retrieve the current life cycle state of this map.
TimeBasedDBUpdateConfig getTimeBasedDBUpdateConfig()
          Get the time-based database update configuration object.
int getTimeToLive()
          Gets the number of seconds for an entry to live.
TTLType getTtlEvictorType()
          Gets how expiration time of a BackingMap entry is computed.
java.lang.String getWriteBehind()
          Get the write-behind parameter.
void removeDynamicIndex(java.lang.String name)
          Removes a dynamic index on the BackingMap.
void removeMapEventListener(EventListener eventListener)
          Removes an EventListener from this BackingMap.
void removeMapEventListener(MapEventListener eventListener)
          Deprecated. This method is deprecated in version 7.1.1, use the removeMapEventListener(EventListener) method.
void setCopyKey(boolean copy)
          Sets whether or not the key needs to be copied when a map entry is created.
void setCopyMode(CopyMode mode, java.lang.Class valueInterface)
          Sets the CopyMode.
void setEvictionTriggers(java.lang.String evictionTriggers)
          Sets the types of additional eviction triggers, all evictors for the backing map will use the provided set of triggers.
void setEvictor(Evictor e)
          Associates an Evictor with this BackingMap.
void setLoader(Loader loader)
          Associates a Loader with this BackingMap.
void setLockStrategy(LockStrategy lockStrategy)
          Sets the LockStrategy.
void setLockTimeout(int seconds)
          Sets the lock timeout used by the lock manager for this BackingMap.
void setMapEventListeners(java.util.List eventListenerList)
          Deprecated. This method is deprecated in version 7.1.1. Use the addMapEventListener(EventListener) or removeMapEventListener(EventListener) methods. Plugins that implement the ObjectGridLifecycleListener interface are automatically registered with the grid. Using this method will remove those automatically added listeners.
void setMapIndexPlugins(java.util.List indexList)
          Sets the list of MapIndexPlugin objects for this BackingMap.
void setNullValuesSupported(boolean nullValuesSupported)
          Sets whether this BackingMap supports null values.
void setNumberOfBuckets(int numBuckets)
          Sets the number of buckets used by this BackingMap.
void setNumberOfLockBuckets(int numBuckets)
          Sets the number of lock buckets used by the lock manager for this BackingMap.
void setObjectTransformer(ObjectTransformer t)
          Sets the ObjectTransformer object for use by this BackingMap and/or Loader.
void setOptimisticCallback(OptimisticCallback checker)
          Sets the OptimisticCallback.
void setPreloadMode(boolean async)
          Sets the preload mode if a Loader is set for this BackingMap.
void setReadOnly(boolean readOnlyEnabled)
          Sets the map type of this BackingMap.
void setTimeBasedDBUpdateConfig(TimeBasedDBUpdateConfig dbUpdateConfig)
          Set the time-based database update configuration object.
void setTimeToLive(int seconds)
          Sets "time to live" of each map entry in seconds.
void setTtlEvictorType(TTLType type)
          Sets how expiration time of a BackingMap entry is computed.
void setWriteBehind(java.lang.String writeBehindParam)
          Enable write-behind updates for this map.
  http://publib.boulder.ibm.com/infocenter/wdpxc/v2http://pic.dhe.ibm.com/infocenter/wxsinfo/v8r6/topic/com.ibm.websphere.extremescale.javadoc.doc/topics/com/ibm/websphere/objectgrid/plugins/TransactionCallback.html http://publib.boulder.ibm.com/infocenter/wdpxc/v2http://pic.dhe.ibm.com/infocenter/wxsinfo/v8r6/topic/com.ibm.websphere.extremescale.javadoc.doc/topics/com/ibm/websphere/objectgrid/
Methods inherited from interface com.ibm.websphere.objectgrid.ClientReplicableMap

disableClientReplication, enableClientReplication, getReplicationMode
 

Field Detail

DEFAULT_LOCK_TIMEOUT

static final int DEFAULT_LOCK_TIMEOUT

Default lock timeout used if setLockTimeout(int) is not invoked.

DEFAULT_NUMBER_OF_BUCKETS

static final int DEFAULT_NUMBER_OF_BUCKETS

Default number of lock buckets used if setNumberOfBuckets(int) is not invoked.

DEFAULT_NUMBER_OF_LOCK_BUCKETS

static final int DEFAULT_NUMBER_OF_LOCK_BUCKETS

Default number of lock buckets used if setNumberOfLockBuckets(int) is not invoked.

EVICTIONTRIGGER_MEMORY_USAGE_THRESHOLD

static final java.lang.String EVICTIONTRIGGER_MEMORY_USAGE_THRESHOLD

The eviction trigger string constant to enable memory based eviction using memory usage threshold provided by the java.lang.management.MemoryPoolMXBean.

Since:
WAS XD 6.1.0.3
Constant Field Values

LOCAL

static final int LOCAL

Constant used to indicate this map is not a distributed map.

Since:
WAS XD 6.1
Constant Field Values

SERVER

static final int SERVER

Constant used to indicate this map is a server map.

Since:
WAS XD 6.1
Constant Field Values

CLIENT

static final int CLIENT

Constant used to indicate this map is a client to a server map

Since:
WAS XD 6.1
Constant Field Values
Method Detail

getName

java.lang.String getName()

Gets the name of the BackingMap.

Returns:
value specified when BackingMap was created.

setEvictor

void setEvictor(Evictor e)

Associates an Evictor with this BackingMap.

An Evictor aids with cleaning up the cache based on whatever algorithm is desired (LRU, LFU, etc). Passing null to this method removes a previously set Evictor object from an earlier invocation of this method.

Note, to avoid an IllegalStateException, this method must be called prior to the ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

An Evictor that implements the BackingMapLifecycleListener is automatically added as if the addMapEventListener(EventListener) method was called. Any previous evictor which implements BackingMapLifecycleListener is removed as if the removeMapEventListener(EventListener) method was called.

An Evictor may also implement the BackingMapPlugin interface in order to receive enhanced BackingMap plug-in lifecycle method calls. The plug-in is then also required to correctly implement each of the bean methods related to introspection of its state (for example isInitialized(), isDestroyed(), etc).

Parameters:
e - Evictor instance
Throws: ObjectGrid.initialize(), ObjectGrid.getSession()

getEvictor

Evictor getEvictor()

Gets the Evictor being used by this BackingMap.

Returns:
the argument that was passed to the setEvictor(Evictor) method of this interface or null if setEvictor was not previously called setEvictor(Evictor)

setObjectTransformer

void setObjectTransformer(ObjectTransformer t)

Sets the ObjectTransformer object for use by this BackingMap and/or Loader.

An ObjectTransformer aids with the "serialization" of non-Serializable objects. It allows a custom copy function to be installed for more efficient object copy operations.

Note, to avoid an IllegalStateException, this method must be called prior to the ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

An ObjectTransformer that implements the BackingMapLifecycleListener is automatically added as if the addMapEventListener(EventListener) method was called. Any previous transformer which implements BackingMapLifecycleListener is removed as if the removeMapEventListener(EventListener) method was called.

Parameters:
t - ObjectTransformer instance
Throws:
java.lang.IllegalArgumentException - if the passed in ObjectTransformer is null ObjectGrid.initialize(), ObjectGrid.getSession()

getObjectTransformer

ObjectTransformer getObjectTransformer()

Gets the ObjectTransformer object being used by this BackingMap and/or Loader.

Returns:
the argument that was passed to the setObjectTransformer(ObjectTransformer) setObjectTransformer(ObjectTransformer)

setOptimisticCallback

void setOptimisticCallback(OptimisticCallback checker)

Sets the OptimisticCallback.

The OptimisticCallback will be used to check the versions of cache entries during the commit phase. If no OptimisticCallback was previously set, a default OptimisticCallback will be used. For Entities, the default OptimisticCallback will use a version field that was specified in the entity metadata. For POJO objects or Entities that do not have a version field specified, the default OptimisticCallback uses the entire object as the version value. In order for it to work for POJO objects, the application's value object needs to have a useful equals(Object) method. If the application does not require versioning, but is using Optimistic locking, the NoVersioningOptimistCallback should be used.

Note, to avoid an IllegalStateException, this method must be called prior to the ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

An OptimisticCallback that implements the BackingMapLifecycleListener is automatically added as if the addMapEventListener(EventListener) method was called. Any previous optimistic callback which implements BackingMapLifecycleListener is removed as if the removeMapEventListener(EventListener) method was called.

Parameters:
checker - OptimisticCallback instance
Throws:
java.lang.IllegalArgumentException - if the passed in OptimisticCallback is null NoVersioningOptimisticCallback, LockStrategy.OPTIMISTIC, ObjectGrid.initialize(), ObjectGrid.getSession()

getOptimisticCallback

OptimisticCallback getOptimisticCallback()

Gets the OptimisticCallback being used by this BackingMap and/or Loader or null if the LockStrategy is not optimistic.

If no OptimisticCallback was previously set, a default OptimisticCallback will be used. For Entities, the default OptimisticCallback will use a version field that was specified in the entity metadata. For POJO objects or Entities that do not have a version field specified, the default OptimisticCallback uses the entire object as the version value. In order for it to work for POJO objects, the application's value object needs to have a useful equals(Object) method. If the application does not require versioning, but is using Optimistic locking, the NoVersioningOptimistCallback should be used.

Returns:
the argument that was passed to the setOptimisticCallback(OptimisticCallback) method of this interface or the default OptimisticCallback object if the setOptimisticCallback method was not previously called for this object. If Optimistic locking is not being used, this method will return null after ObjectGrid.initialize() OptimisticCallback, LockStrategy.OPTIMISTIC, setOptimisticCallback(OptimisticCallback)

setLoader

void setLoader(Loader loader)

Associates a Loader with this BackingMap.

Only one Loader can be associated with a given BackingMap. Passing null to this method removes a previously set Loader object from an earlier invocation of this method and indicates that this BackingMap is not associated with a Loader.

Note, to avoid an IllegalStateException, this method must be called prior to the ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

A loader that implements the BackingMapLifecycleListener is automatically added as if the addMapEventListener(EventListener) method was called. Any previous loader which implements BackingMapLifecycleListener is removed as if the removeMapEventListener(EventListener) method was called.

A Loader may also implement the BackingMapPlugin interface in order to receive enhanced BackingMap plug-in lifecycle method calls. The plug-in is then also required to correctly implement each of the bean methods related to introspection of its state (for example isInitialized(), isDestroyed(), etc).

Parameters:
loader - Loader instance
Throws: ObjectGrid.initialize(), ObjectGrid.getSession()

getLoader

Loader getLoader()

Gets the Loader being used by this BackingMap.

Returns:
the argument that was passed to the setLoader(Loader) method of this interface or null if setLoader was not previously called for this setLoader(Loader)

setPreloadMode

void setPreloadMode(boolean async)

Sets the preload mode if a Loader is set for this BackingMap.

If the parameter is true then the Loader.preloadMap(Session, BackingMap) is invoked asynchronously; otherwise it blocks the execution when loading data so the cache is unavailable until preload completes. Preloading occurs during ObjectGrid initialization.

Note, to avoid an IllegalStateException, this method must be called prior to the ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

Parameters:
async - If this is true then the cache is loaded asynchronously otherwise it blocks and the cache is unavailable until preload completes.
Throws:

getPreLoadMode

boolean getPreLoadMode()

Returns whether this BackingMap will be asynchronously preloaded or not if a Loader is set.

If true is returned then the Loader.preloadMap(Session, BackingMap) method is invoked asynchronously; otherwise it blocks the execution when loading data so the cache is unavailable until preload completes. Preloading occurs during ObjectGrid initialization.

Returns:
the argument that was passed to the setPreloadMode(boolean) method of this interface or false if setPreloadeMode was not previously setPreloadMode(boolean)

addMapIndexPlugin

void addMapIndexPlugin(MapIndexPlugin index)
                       throws IndexAlreadyDefinedException

Adds an MapIndexPlugin to this Map. This method assumes the index implementation was constructed with the name of the attribute to index. The name of the index is specified when the index is constructed.

Note, to avoid an IllegalStateException, this method must be called prior to ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

A MapIndexPlugin that implements the BackingMapLifecycleListener is automatically added as if the addMapEventListener(EventListener) method was called. Any previous index which implements BackingMapLifecycleListener is removed as if the removeMapEventListener(EventListener) method was called.

Parameters:
index - The index implementation.
Throws:
IndexAlreadyDefinedException - if this index already exists. ObjectGrid.initialize(), ObjectGrid.getSession()

getMapIndexPlugins

java.util.List getMapIndexPlugins()

Returns the current list of MapIndexPlugin objects for this BackingMap.

Returns:
The current list of MapIndexPlugins for this BackingMap. The list is empty if the addMapIndexPlugin(MapIndexPlugin) or setMapIndexPlugins(List) method was setMapIndexPlugins(List)

setMapIndexPlugins

void setMapIndexPlugins(java.util.List indexList)

Sets the list of MapIndexPlugin objects for this BackingMap. If the BackingMap already has a List of MapIndexPlugin objects, that list is replaced by the List passed as an argument to the current invocation of this method.

Note, to avoid an IllegalStateException, this method must be called prior to ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

Parameters:
indexList - A non-null reference to a List of MapIndexPlugin objects.
Throws:
java.lang.IllegalArgumentException - is thrown if indexList is null or the indexList contains either a null reference ObjectGrid.initialize(), ObjectGrid.getSession()

setCopyMode

void setCopyMode(CopyMode mode,
                 java.lang.Class valueInterface)

Sets the CopyMode.

The CopyMode determines whether a get operation of an entry in the BackingMap returns the actual value, a copy of the value, or a proxy for the value. In the case of a proxy, the copy of the value does not occur unless a set method of the application provided value interface is invoked. It also determines that when a transaction is committed, whether a copy of the value object of an entry that was marked as dirty by the transaction is put into the BackingMap at commit time. The CopyMode does not specify if the object is copied when being read or written to a Loader. It is the responsibility of the implementor of a Loader to make copies as appropriate. The default CopyMode is CopyMode.COPY_ON_READ_AND_COMMIT.

Note, to avoid an IllegalStateException, this method must be called prior to the ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

Parameters:
mode - must be one of the final static variables defined in CopyMode. See CopyMode class for an explanation of each mode and how the valueInterface is used for CopyMode.COPY_ON_WRITE .
valueInterface - the value interface Class object. Specify null in version 7.1 and later.
Throws:
java.lang.IllegalArgumentException - if mode is CopyMode.COPY_ON_WRITE and valueInterface parameter is null and CGLIB isn't in the classpath. ObjectGrid.initialize(), ObjectGrid.getSession()

getCopyMode

CopyMode getCopyMode()

Gets the CopyMode being used by this BackingMap.

Returns:
the argument that was passed to the setCopyMode(CopyMode, Class) method of this interface or the default CopyMode object if setCopyMode was not previously setCopyMode(CopyMode, Class)

setLockStrategy

void setLockStrategy(LockStrategy lockStrategy)

Sets the LockStrategy.

The locking strategy represented by the LockStrategy object determines if the internal ObjectGrid lock manager is used whenever a map entry is accessed by a transaction. The default strategy is LockStrategy.OPTIMISTIC.

Note, to avoid an IllegalStateException, this method must be called prior to the ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

Parameters:
lockStrategy - must be one of the final static variables defined in LockStrategy. See LockStrategy class for an explanation of each locking strategy.
Throws: ObjectGrid.initialize(), ObjectGrid.getSession()

getLockStrategy

LockStrategy getLockStrategy()

Gets the LockStrategy object being used by this BackingMap.

Returns:
the argument that was passed to the setLockStrategy(LockStrategy) method of this interface or the default LockStrategy object if setLockStrategy was not previously setLockStrategy(LockStrategy)

setMapEventListeners

@Deprecated
void setMapEventListeners(java.util.List eventListenerList)

Deprecated. This method is deprecated in version 7.1.1. Use the addMapEventListener(EventListener) or removeMapEventListener(EventListener) methods. Plugins that implement the ObjectGridLifecycleListener interface are automatically registered with the grid. Using this method will remove those automatically added listeners.

Sets the list of EventListener objects.

If this BackingMap already has a List of EventListeners, that list is replaced by the List passed as an argument to the current invocation of this method. This method can be called before and after the ObjectGrid.initialize() method.

Parameters:
eventListenerList - A non-null reference to a List of EventListener objects that are instances of BackingMapLifecycleListener or MapEventListener
Throws:
java.lang.IllegalArgumentException - is thrown if eventListenerList is null, the eventListenerList contains either a null MapEventListener, BackingMapLifecycleListener, addMapEventListener(EventListener), removeMapEventListener(EventListener)

getMapEventListeners

java.util.List getMapEventListeners()

Gets the current list of EventListeners.

MapEventListener, BackingMapLifecycleListener

addMapEventListener

void addMapEventListener(EventListener eventListener)

Adds an EventListener to this BackingMap.

Note, this method is allowed to be invoked before and after the ObjectGrid.initialize() method. Backing map plug-ins (Loader, Evictor, MapIndexPlugin, ObjectTransformer, OptimisticCallback) that implement the ObjectGridLifecycleListener are automatically added as listeners when added to the BackingMap.

Parameters:
eventListener - A non-null reference to a EventListener to add to the list. The listener must be an instance of BackingMapLifecycleListener or MapEventListener
Throws: MapEventListener, BackingMapLifecycleListener

addMapEventListener

void addMapEventListener(MapEventListener eventListener)

Deprecated. This method is deprecated in version 7.1.1, use the addMapEventListener(EventListener) method.

Provided for compatibility with old releases, use the addMapEventListener(EventListener) method.

Parameters:
listener -

removeMapEventListener

void removeMapEventListener(EventListener eventListener)

Removes an EventListener from this BackingMap.

Note, this method is allowed to be invoked before and after the ObjectGrid.initialize() method. Backing map plug-ins (Loader, Evictor, MapIndexPlugin, ObjectTransformer, OptimisticCallback) that implement the ObjectGridLifecycleListener are automatically removed as listeners when removed from the ObjectGrid.

Parameters:
eventListener - A non-null reference to an event listener that was previously added by invoking either the addMapEventListener(EventListener) or setMapEventListeners(List) method of this interface.
Throws: MapEventListener, BackingMapLifecycleListener, addMapEventListener(EventListener)

removeMapEventListener

void removeMapEventListener(MapEventListener eventListener)

Deprecated. This method is deprecated in version 7.1.1, use the removeMapEventListener(EventListener) method.

Provided for compatibility with old releases, use the removeMapEventListener(EventListener) method.

Parameters:
listener -

getPartitionId

int getPartitionId()

Gets the partition identifier being used by this BackingMap.

Returns:
The 0-based index for the partition represented by this BackingMap instance. If there is only a single partition defined for this BackingMap object, a 0 will be returned (default).
Since:
WAS XD 6.0.1

setReadOnly

void setReadOnly(boolean readOnlyEnabled)

Sets the map type of this BackingMap.

A map can be a read only map or a read/write map. Passing true as the parameter value will make this map a read only map; passing false as the parameter value will make this map a read/write map.

Note, to avoid an IllegalStateException, this method must be called prior to the ObjectGrid.initialize() method. Also, keep in mind that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if it has yet to be called by the application.

Parameters:
readOnlyEnabled - If set to true, this BackingMap will be a read only map. If false, the map will be a read/write map.
Throws:
java.lang.IllegalStateException - if this method is called after the ObjectGrid.initialize() method is called.

getReadOnly

boolean getReadOnly()

Retrieves the map type.

Returns:
the argument that was passed to setReadOnly(boolean) method of this interface. True is returned if this a read only map. A return value of false implies that this is a read/write map. If setReadOnly was never called, the default return

getObjectGrid

ObjectGrid getObjectGrid()

Gets the ObjectGrid that owns this BackingMap.

Returns:
the ObjectGrid instance that owns this BackingMap.

setNumberOfBuckets

void setNumberOfBuckets(int numBuckets)

Sets the number of buckets used by this BackingMap.

The BackingMap implementation uses a hash map for its implementation. If there are a lot of entries in the BackingMap then more buckets means better performance because the risk of collisions is lower as the number of buckets grows. More buckets also means more concurrency. If number of buckets is 0, no entries will be stored in the map, but the appropriate ObjectGrid and BackingMap plug-ins will still be called.

Once the ObjectGrid is initialized this parameter