Home

WebSphere eXtreme Scale v8.6 - Configuration files

+

Search Tips   |   Advanced Search

1. Server properties file
   1. Server properties
   2. diskOverflowCapBytes
   3. diskStoragePath
   4. diskOverflowMinDiskSpaceBytes
   5. diskOverflowEnabled
   6. enableMBeans
   7. haManagerPort
   8. hpelEnable
   9. hpelRepositoryLocation
   10. hpelEnablePurgeBySize
   11. hpelEnablePurgeByTime
   12. hpelEnableFileSwitch
   13. hpelEnableBuffering
   14. hpelIncludeTrace
   15. hpelOutOfSpaceAction
   16. hpelOutputFormat
   17. hpelMaxRepositorySize
   18. hpelMaxRetentionTime
   19. hpelFileSwitchHour
   20. JMXConnectorPort
   21. JMXServicePort
   22. listenerPort
   23. syslogEnabled
   24. syslogHostName
   25. syslogHostPort
   26. syslogFacility
   27. syslogThreshold
   28. xioTimeout
   29. catalogServiceEndPoints
   30. enableXM
   31. maxXIONetworkThreads
   32. maxXIOWorkerThreads
   33. maxXMSize
   34. minXIONetworkThreads
   35. minXIOWorkerThreads
   36. xioChannel.xioContainerTCPNonSecure.Port
   37. xioChannel.xioContainerTCPSecure.Port
   38. catalogClusterEndPoints
   39. enableManagementConcentrator
   40. logNotificationFilter
   41. transport
   42. Security server properties
2. Client properties file
   1. Sample client properties file
   2. Specify a client properties file for Java clients
   3. Specify a client properties file for .NET clients
   4. Client properties
   5. Security client properties
   6. transportType
3. REST data service properties file
   1. WebSphere eXtreme Scale configuration
   2. Entity model
   3. Mapping between EDM data types and Java data types
   4. Mapping Java types to EDM types
   5. Mapping from EDM types to Java types
   6. Mapping temporal types
   7. Associations
4. ObjectGrid descriptor XML file
   1. objectGridConfig element
   2. objectGrids element
   3. objectGrid element
   4. backingMap element
   5. nearCacheEnabled
   6. nearCacheInvalidationEnabled
   7. nearCacheLastAccessTTLSyncEnabled
   8. numberOfBuckets
   9. bean element
   10. property element
   11. backingMapPluginsCollections element
   12. backingMapPluginCollection element
   13. querySchema element
   14. mapSchemas element
   15. mapSchema element
   16. relationships element
   17. relationship element
   18. stream element
   19. view element
   20. basic element
   21. id element
   22. objectGrid.xsd file
5. Deployment policy descriptor XML file
   1. mapSet element (line 3)
   2. map element (line 14)
   3. zoneMetadata element (line 16)
   4. shardMapping element (line 17)
   5. zoneRule element (line 20)
   6. zone element (lines 23 to 25)
   7. deploymentPolicy.xsd file
6. Entity metadata descriptor XML file
   1. id element
   2. basic element
   3. id-class element
   4. transient element
   5. version element
   6. cascade-type element
   7. one-to-one element
   8. one-to-many element
   9. many-to-one element
   10. many-to-many element
   11. attributes element
   12. Entity element
   13. entity-mappings element
   14. entity-listener element
   15. PrePersist element
   16. PostPersist element
   17. PreRemove element
   18. PreUpdate element
   19. PostUpdate element
   20. PostLoad element
   21. emd.xsd file
   22. emd.xsd file
7. Security descriptor XML file
   1. securityConfig element
   2. security element
   3. authenticator element
   4. adminAuthorization element
   5. systemCredentialGenerator element
   6. property element
   7. objectGridSecurity.xsd file
8. Spring descriptor XML file
   1. register element
   2. server element
   3. catalog element
   4. catalogServerProperties element
   5. foreignDomains element
   6. foreignDomain element
   7. endPoint element
   8. catalog server endpoint element
   9. container element
   10. JPALoader element
   11. JPATxCallback element
   12. JPAEntityLoader element
   13. LRUEvictor element
   14. LFUEvictor element
   15. HashIndex element
   16. Spring objectgrid.xsd file
   17. Spring objectgrid.xsd file
9. Liberty profile configuration files
   1. Liberty profile server properties
   2. Liberty profile web feature properties
   3. Liberty profile webApp feature properties
   4. Liberty profile webGrid feature properties

Server properties file

Contains several properties that define different settings for your server, such as...

• trace settings
• logging
• security configuration

The server properties file is used by both catalog service and container servers in both stand-alone servers and servers hosted in WebSphere Application Server.

To create your server properties file use...

wxs_home/properties/sampleServer.properties

Specifying a setting by using one of the items later in the list overrides the previous setting. For example, if you specify a system property value for the server properties file, the properties in that file override the values in the objectGridServer.properties file that is in the classpath.

• For servers that run in WebSphere Application Server:

  • Use a well-named file in the classpath, for example was_root/properties. If you put this well-named file in the current directory, the file is not found unless the current directory is in the classpath. The name used follows:

    objectGridServer.properties

  • Specify a system property that specifies a file in the system current directory. Put the file in the was_root/properties directory. The file cannot be in the classpath:

    -Dobjectgrid.server.props=file_name

• For stand-alone servers:

  • Use a well-named file in the classpath, for example wxs_home /properties. If you put this well-named file in the current directory, the file is not found unless the current directory is in the classpath. The name used follows:

    objectGridServer.properties

  • Specify the server properties file as a parameter when we run the start server command. We can override these properties manually to specify a file in the system current directory:

    -serverProps file_name

• For embedded, stand-alone servers:

  Use the embedded server API. Use the ServerFactory.getServerProperties and ServerFactory.getCatalogServerProperties methods. The data in the object is populated with the data from the properties files.

Server properties

General properties

diskOverflowCapBytes

Maximum amount of disk space used by this server for disk overflow, in bytes. The default value specifies that there is no limit on how much is stored on disk. false: Long.MAX_VALUE

diskStoragePath

Absolute path to a directory location used for storing overflow content.

diskOverflowMinDiskSpaceBytes

Entries will not be moved to disk if there is less than this amount of space free in diskStoragePath, in bytes. false: 0

diskOverflowEnabled

Enables the native overflow disk feature. Enable eXtreme Memory for this feature to work. false

enableMBeans

Enables ObjectGrid container Managed Beans (MBean). This property applies to both the container server and the catalog service. true

haManagerPort

Port number the high availability manager uses. If this property is not set, a free port is chosen. This property is ignored in WebSphere Application Server environments.

hpelEnable

Specifies if High Performance Extensible Logging (HPEL) is enabled. HPEL logging is enabled when the property is set to true. false

hpelRepositoryLocation

Specifies the HPEL logging repository location. false: "." (the runtime location)

hpelEnablePurgeBySize

Indicates if the HPEL purges log files by size. We can set the size of the files with the hpelMaxRepositorySize property. true (enabled)

hpelEnablePurgeByTime

Indicates if the HPEL purges log files by time. Set the amount of time with the hpelMaxRetentionTime property. true (enabled)

hpelEnableFileSwitch

Indicates if the HPEL file is enabled to create a new file at a specified hour. Use the hpelFileSwitchHour property to specify the hour at which to create a new file. false (disabled)

hpelEnableBuffering

Indicates if the HPEL buffering is enabled. false (disabled)

hpelIncludeTrace

Indicates if the HPEL text files include tracing. false (disabled)

hpelOutOfSpaceAction

Indicates the action to be performed when the disk space has been exceeded. false: PurgeOld

Possible values:

PurgeOld, StopServer, StopLogging

hpelOutputFormat

Indicates the format of the log files to be generated. false: Basic

Possible values:

Basic, Advanced, CBE-1.0.1

hpelMaxRepositorySize

Indicates the maximum size of files, in megabytes. This value is used when you able the hpelEnablePurgeBySize property. false: 50

hpelMaxRetentionTime

Indicates the maximum retention time to hold files, in hours. false: 48

hpelFileSwitchHour

Indicates the hour at which to create a new file. This value is used when the hpelEnableFileSwitch property is enabled. false: 0

JMXConnectorPort

Defines the SSL port to which the Java Management Extensions (JMX) service binds.

JMXServicePort

Port number on which the MBean server listens communication with JMX. The JMXServicePort property specifies the non-SSL port for JMX. You must use a different port number for each JVM in the configuration. To use JMX/RMI, explicitly specify the JMXServicePort and port number, even to use the default port value. This property applies to both the container server and the catalog service. (Required for stand-alone environments only.) false: 1099 for catalog servers

jvmStatsFileName

File name of the CSV statistics file for the JVM. false: jvmstats

jvmStatsLoggingEnabled

When set to true, enables log data for the JVM to be written to a CSV file. true

jvmStatsWriteRate

Specifies the write rate of the CSV statistics files for the JVM in writes per second. false: 10

listenerHost

Host name to which the Object Request Broker (ORB) or eXtremeIO (XIO) transport binds for communication. The value must be a fully-qualified domain name or IP address. If the configuration involves multiple network cards, set the listener host and port to let the transport mechanism in the JVM know the IP address for which to bind. If you do not specify which IP address to use, symptoms such as connection timeouts, unusual API failures, and clients that seem to hang can occur.

listenerPort

Port number to which the Object Request Broker (ORB) or eXtremeIO (XIO) transport binds. This setting configures containers and clients to communicate with the catalog service. In WebSphere Application Server, the listenerPort is inherited by the BOOTSTRAP_ADDRESS port (when we are using the ORB transport) or the XIO_address port (when we are using XIO transport) port configuration. This property applies to both the container server and the catalog service. false: 2809

mapStatsFileName

File name of the CSV statistics file for the map. false: mapstats

mapStatsLoggingEnabled

When set to true, enables log data for the maps on the server to be written to a CSV file. true

mapStatsWriteRate

Specifies the write rate of the CSV statistics files for the map in writes per second. false: 10

maxJVMStatsFiles

Indicates the maximum number of CSV statistics files that are generated for the JVM. false: 5

maxJVMStatsFileSize

Indicates the maximum file size, in megabytes, of the CSV statistics files for the JVM. false: 100

maxMapStatsFileSize

Indicates the maximum file size, in megabytes, of the CSV statistics files for the map. false: 100

maxOGStatsFiles

Indicates the maximum number of CSV statistics files that are generated for the ObjectGrid instance. false: 5

maxOGStatsFileSize

Indicates the maximum file size, in megabytes, of the CSV statistics files for the ObjectGrid instance. false: 100

maxMapStatsFiles

Indicates the maximum number of CSV statistics files that are generated for the map. false: 5

maxThreads

Maximum number of threads used by the internal thread pool in the run time for built-in evictors and DataGrid operations. false: 50

minThreads

Minimum number of threads used by the internal thread pool in the run time for built-in evictors and DataGrid operations. false: 10

ogStatsFileName

File name of the CSV statistics file for the ObjectGrid instance. false: ogstats

ogStatsLoggingEnabled

When set to true, enables log data for the ObjectGrid instance on the server to be written to a CSV file. false

ogStatsWriteRate

Specifies the write rate of the CSV statistics files for the ObjectGrid instance in writes per second. false: 10

serverName

Set the server name used to identify the server. This property applies to both the container server and the catalog service.

syslogEnabled

Enables remote logging for analysis of historical data. You must have a syslog server available to listen for and capture events. false

syslogHostName

Host name or IP address of the remote server on which we want to log historical data.

syslogHostPort

Port number of the remote server on which we want to log historical data.

Valid values:

0-65535 false: 512

syslogFacility

Indicates the type of remote logging facility that is being used.

Valid values:

kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, authpriv, ftp, sys0, sys1, sys2, sys3,local0, local1, local2, local3, local4, local5, local6, local7 false: user

syslogThreshold

Threshold of the severity of messages to send to the remote logging server. To send both warning and severe messages, enter a value of

WARNING. To send severe messages only, enter

SEVERE.

Valid values:

SEVERE,

WARNING false: WARNING

systemStreamToFileEnabled

Enables the container to write the SystemOut, SystemErr, and trace output to a file. If this property is set to false, output is not written to a file and is instead written to the console. true

traceFile

File name to write trace information. This property applies to both the container server and the catalog service. Example: ../logs/c4Trace.log

Restriction: The traceFile property is not supported in the Liberty profile.

traceSpec

Enables trace and the trace specification string for the container server. Trace is disabled by default. This property applies to both the container server and the catalog service. Examples:

• ObjectGrid=all=enabled
• ObjectGrid*=all=enabled

Restriction: The traceSpec property is not supported in the Liberty profile.

workingDirectory

Location to where the container server output is written. When this value is not specified, the output is written to a log directory within the current directory. This property applies to both the container server and the catalog service. no value

xioTimeout

Timeout for server requests that are using the IBM eXtremeIO (XIO) transport in seconds. The value can be set to any value greater than or equal to one second. 30 seconds

zoneName

Set the name of the zone to which the server belongs. This property applies to both the container server and the catalog service.

Container server properties

catalogServiceEndPoints

End points to connect to the catalog service domain. This value must be in the form

host:port,host:port. The host value is the listenerHost value and the port value is the listenerPort value of the catalog server. This property applies to a container server only.

enableXM

When set to true, enables eXtremeMemory on the server and configures the server to use IBM eXtremeIO for synchronous and asynchronous replication. Cache entries are stored in native memory instead of on the Java heap. All container servers in the data grid must use the same value for the enableXM property. false

maxXIONetworkThreads

Set the maximum number of threads to allocate in the eXtremeIO transport network thread pool. 256

maxXIOWorkerThreads

Set the maximum number of threads to allocate in the eXtremeIO transport request processing thread pool. 256

maxXMSize

Set the maximum amount of memory, in megabytes, used by the server for eXtremeMemory storage. 25% of the total memory on the system

memoryThresholdPercentage

Set the memory threshold for memory-based eviction . The percentage specifies the maximum heap to be used in the JVM before eviction occurs. The default value is -1, which indicates that the memory threshold is not set. If the memoryThresholdPercentage property is set, the MemoryPoolMXBean value is set with the provided value. Eviction occurs only if eviction is enabled on an evictor. This property applies to a container server only.

-1

minXIONetworkThreads

Sets the minimum number of threads to allocate in the eXtremeIO transport network thread pool.

1

minXIOWorkerThreads

Set the minimum number of threads to allocate in the eXtremeIO transport request processing thread pool.

1

statsSpec

Statistics specification for the container server.

Examples:

all=disabled : Disables all statistics.

all=enabled : Enables all statistics. For more information about enabling statistics, see Enabling statistics

xioChannel.xioContainerTCPNonSecure.Port

Deprecated: This property has been deprecated. The value specified by the listenerPort property is used. Non-secure listener port number of eXtremeIO on the server. If you do not set the value, an ephemeral port is used. This property is used only when the transportType property is set to TCP/IP.

Restriction: The xioChannel.xioContainerTCPNonSecure.Port property is not supported in the Liberty profile.

xioChannel.xioContainerTCPSecure.Port

Deprecated: This property has been deprecated. The value specified by the listenerPort property is used. SSL port number of eXtremeIO on the server. This property is used only when the transportType property is set to SSL-Supported or SSL-Required.

Catalog service properties

catalogClusterEndPoints

For stand-alone configurations only. Specifies a list of catalog service domain end points for the catalog service. This property specifies the catalog service end points to start the catalog service domain. Use the following comma-separated format:

serverName:hostName:clientPort:peerPort,<serverName:hostName:clientPort:peerPort>

serverName

Name of the catalog server.

hostName

Host name for the computer where the server is launched.

clientPort

Port used for peer catalog service communication.

peerPort

This value is the same as the haManagerPort. Port used for peer catalog service communication.

This property applies to the catalog service only. If you start additional catalog servers, they must include the same servers in the catalogClusterEndPoints property. The order of the list can be different, but the servers contained in the list must be the same for each catalog server. Do not put any spaces in the list.

domainName

For stand-alone configurations only. Specifies the domain name used to uniquely identify this catalog service domain to clients when routing to multiple domains. This property applies to the catalog service only.

enableManagementConcentrator

Specifies if the catalog server is a hub for the message center. This property is enabled by default. To disable the hub, set the value to false. true

enableQuorum

Enables quorum for the catalog service. Quorum is used to ensure that a majority of the catalog service domain is available before moving partitions on the available container servers. To enable quorum, set the value to true or enabled. The default value is

disabled. This property applies to the catalog service only.

<foreignDomain>.endpoints

Connection information for the catalog servers of the foreign domains, such as domain B:

For example:

B.endPoints=hostB1:2809, hostB2:2809

If a foreign domain has multiple catalog servers, specify all of them.

foreignDomains

Names of catalog service domains to which we want to link in a multi-master replication topology. This property applies to the catalog service only.

Restriction: The foreignDomains property is not supported in the Liberty profile.

heartBeatFrequencyLevel

Specifies how often a server failover is detected. An aggressive heartbeat interval can be useful when the processes and network are stable. If the network or processes are not optimally configured, heartbeats might be missed, which can result in a false failure detection . The heartbeat frequency level is a trade-off between use of resources and failure discovery time. The more frequently heartbeats occur, more resources are used, but failures are discovered more quickly. This property applies to the catalog service only.

Value	Action	Description
0	Typical (default)	Heartbeat level at a typical rate. With this value, failover detection occurs at a reasonable rate without overusing resources. Failovers are typically detected within 30 seconds.
-1	Aggressive	Aggressive heartbeat level. With this value, failures are detected more quickly, but also uses additional processor and network resources. This level is more sensitive to missing heartbeats when the server is busy. Failovers are typically detected within 5 seconds.
1	Relaxed	Relaxed heartbeat level. With this value, a decreased heartbeat frequency increases the time to detect failures, but also decreases processor and network use. Failovers are typically detected within 180 seconds.

isCatalog

For stand-alone configurations only. When set to true, the server process automatically starts a catalog service.

false : false

logNotificationFilter

Specifies a regular expression that filters all messages, including the INFO level log messages. This filter determines which messages generate health monitoring events. If you do not specify a regular expression, INFO level log messages are not published through the health monitoring framework. By default, only WARNING and SEVERE level messages generate health monitoring events.

Example: logNotificationFilter=.*DYNACACHE.*

placementDeferralInterval

Specifies the interval in milliseconds for deferring the balancing and placement of work items to the container servers. Increasing the deferral interval lowers processor utilization, but the placement of work items is completed over time. A decrease in the deferral interval increases short-term processor utilization, but the placement of work items is more immediate and expedited. 15000 ms

transport

Type of transport to use for all the servers in the catalog service domain. We can set the value to XIO or ORB.

When you use the startOgServer or startXsServer commands, you do not need to set this property. The script overrides this property. However, if you start servers with another method, the value of this property is used.

This property applies to the catalog service only.

If you have both the -transport parameter on the start script and the transport server property defined on a catalog server, the value of the -transport parameter is used.

Security server properties

The server properties file is also used to configure eXtreme Scale server security. You use a single server property file to specify both the basic properties and the security properties.

General security properties

credentialAuthentication

Indicates whether this server supports credential authentication. Choose one of the following values:

• Never: The server does not support credential authentication.
• Supported: The server supports the credential authentication if the client also supports credential authentication.
• Required: The client requires credential authentication.

securityEnabled

Enables the container server security when set to true. The default value is false. This property must match the securityEnabled property specified in the objectGridSecurity.xml file that is provided to the catalog server.

Transport layer security settings

transportType

Server transport type. Use one of the following values:

• TCP/IP: Indicates that the server supports TCP/IP connections only.
• SSL-Supported: Indicates that the server supports both TCP/IP and SSL connections. (false)
• SSL-Required: Indicates that the server requires SSL connections.

SSL configuration properties

alias

Alias name in the keystore. This property is used if the keystore has multiple key pair certificates and we want to select one of the certificates. no value

contextProvider

Name of the context provider for the trust service. If you indicate a value that is not valid, a security exception results that indicates that the context provider type is incorrect.

Valid values:
IBMJSSE2,
IBMJSSE,
IBMJSSEFIPS, and so on.

customSecureTokenManagerProps

Custom SecureTokenManager implementation class properties. This property is used only if the secureTokenManagerType value is

custom. The value is set to the SecureTokenManager Object with the setProperties(String) method.

customTokenManagerClass

Name of your SecureTokenManager implementation class, if you specified the SecureTokenManagerType property value as

custom. The implementation class must have a default constructor to be instantiated.

keyStore

Fully qualified path to the keystore file.

Example: etc/test/security/client.private

keyStorePassword

String password to the keystore. We can encode this value or use the actual value.

keyStoreType

Indicates the type of keystore. If you indicate a value that is not valid, a runtime security exception results.

Valid values:

JKS,
JCEK,
PKCS12, and so on.

protocol

Indicates the type of security protocol to use for the client. Set this protocol value based on which Java Secure Socket Extension (JSSE) provider you use. If you indicate a value that is not valid, a security exception results that indicates that the protocol value is incorrect.

Valid values:

SSL,
SSLv3,
TLS,
TLSv1, and so on.

SecureTokenManager

The SecureTokenManager setting is used for protecting the secret string for server mutual authentications and for protecting the single sign-on token.

secureTokenManagerType

Type of SecureTokenManager setting. You must use the same secureTokenManagerType setting in all of the servers in the catalog service domain, and all servers in linked catalog service domains.Use one of the following settings:

none	Indicates that no secure token manager is used. A secure token manager is required to protect the authenticationSecret attribute value when it is transmitted over the network. This setting also disables the use of a single sign-on token. For security, use the autoSecret setting.
default	Indicates that a token manager that is supplied with the WebSphere eXtreme Scale product is used. You must provide a SecureToken keystore configuration.
autoSecret	Indicates that a token manager that is supplied with the WebSphere eXtreme Scale product is used. This setting provides encryption for server authentication and single sign on tokens, but does not require additional configuration items. Security depends on a hard to guess authenticationSecret attribute value.
custom	Indicates that you have your own token manager specified with the SecureTokenManager implementation class.

trustStore

Fully qualified path to the truststore file.

Example: etc/test/security/server.public

trustStorePassword

Specifies a string password to the truststore. We can encode this value or use the actual value.

trustStoreType

Indicates the type of truststore. If you indicate a value that is not valid, a runtime security exception results.

Valid values:

JKS,
JCEK,
PKCS12, and so on.

Secure token keystore configuration

secureTokenKeyStore

File path name for the keystore that stores the public-private key pair and the secret key.

secureTokenKeyStoreType

Specifies the keystore type, for example, JCKES. We can set this value based on the Java Secure Socket Extension (JSSE) provider that you use. However, this keystore must support secret keys.

secureTokenKeyPairAlias

Alias of the public-private key pair used for signing and verifying.

secureTokenKeyPairPassword

Password to protect the key pair alias used for signing and verifying.

secureTokenSecretKeyAlias

Secret key alias used for ciphering.

secureTokenSecretKeyPassword

Password to protect the secret key.

secureTokenCipherAlgorithm

Algorithm used for providing a cipher. We can set this value based on the Java Secure Socket Extension (JSSE) provider that you use.

secureTokenSignAlgorithm

Algorithm used for signing the object. We can set this value based on the JSSE provider that you use.

Authentication string

authenticationSecret

Secret string to challenge the server. When a server starts, it must present this string to the president server or catalog server. If the secret string matches what is in the president server, this server is allowed to join in. All of the servers in a catalog service domain, and all of the servers in any linked catalog service domains must use the same value for the authenticationSecret setting. The authenticationSecret value must be a long, hard to guess string. Do not use the authenticationSecret value that is in the sampleServer.properties in production deployments.

Client properties file

Sample client properties file

For Java...

wxs_home/properties/sampleClient.properties

For .NET...

net_client_home\config\Client.Net.properties

Specify a client properties file for Java clients

We can specify the client properties file in one of the following ways. Specifying a setting by using one of the items later in the list overrides the previous setting. For example, if you specify a system property value for the client properties file, the properties in that file override the values in the objectGridClient.properties file that is in the class path.

1. As a well-named file anywhere in the class path. Putting this file in the system current directory is not supported:
   objectGridClient.properties

2. As a system property in either a stand-alone or WebSphere Application Server configuration. This value can specify a file in the system current directory, but not a file in the class path:
   -Dobjectgrid.client.props=file_name

3. As a programmatic override using the ClientClusterContext.getClientProperties method. The data in the object is populated with the data from the properties files. We cannot configure security properties with this method.

Specify a client properties file for .NET clients

The default client properties file is...

net_client_home\config\Client.Net.properties

To specify your own property files, supply the full property file path to each Connect method call.

IGridManager gm = GridManagerFactory.GetGridManager( );
ICatalogDomainInfo cdi = gm.CatalogDomainManager.CreateCatalogDomainInfo( "localhost:2809" );
ccc = gm.Connect( cdi, @"C:\MyLocation\MyClient.properties" );
grid = gm.GetGrid( ccc, gridName );

Client properties

Client properties

listenerHost

Host name to which the Object Request Broker (ORB) or eXtremeIO (XIO) transport binds for communication. The value must be a fully-qualified domain name or IP address. If the configuration involves multiple network cards, set the listener host and port to let the transport mechanism in the JVM know the IP address for which to bind. If you do not specify which IP address to use, symptoms such as connection timeouts, unusual API failures, and clients that seem to hang can occur.

listenerPort

Port number to which the Object Request Broker (ORB) or eXtremeIO (XIO) transport binds. This setting configures containers and clients to communicate with the catalog service. In WebSphere Application Server, the listenerPort is inherited by the BOOTSTRAP_ADDRESS port (when we are using the ORB transport) or the XIO_address port (when we are using XIO transport) port configuration. This property applies to both the container server and the catalog service.

preferLocalProcess

This property is not currently used. It is reserved for future use.

preferLocalHost

This property is not currently used. It is reserved for future use.

preferZones

Specifies a list of preferred routing zones. Each specified zone is separated by a comma in the form:

preferZones=ZoneA,ZoneB,ZoneC no value

requestRetryTimeout

Specifies how long to continue processing a request (in milliseconds). Use one of the following valid values:

• A value of

  0 indicates that the request should fail fast and skip over the internal retry logic.

• A value of

  -1 indicates that the request retry timeout is not set, meaning that the request duration is governed by the transaction timeout. (false )

• A value over

  0 indicates the request entry timeout value in milliseconds. Exceptions that are not successfully created are returned. Even when exceptions, such as DuplicateException, are tried again, they are also returned when they do not succeed. The transaction timeout is still used as the maximum time to wait.

shuffleBootstrapAddresses

Specifies if the catalog service addresses should be randomized when used by a client while bootstrapping to the data grid. The values must be either true or false. true

Security client properties

General security properties

securityEnabled

Enables WebSphere eXtreme Scale client security. This setting should match with the securityEnabled setting in theWebSphere eXtreme Scale server properties file. If the settings do not match, the client connection to the data grid fails. false

Credential authentication configuration properties

credentialAuthentication

Client credential authentication support. Use one of the following valid values:

• Never: The client does not support credential authentication.
• Supported: The client supports credential authentication if the server also supports credential authentication. (false )
• Required: The client requires credential authentication.

authenticationRetryCount

Number of times that authentication is tried if the credential is expired. If the value is set to 0, attempts to authenticate are not tried again. false: 3

credentialGeneratorAssembly

Name of the assembly used to generate credentials for the .NET client. The value must be a valid C# .dll assembly name with version, culture and other properties included.

Example:

IBM.WebSphere.Caching.CredentialGenerator, Version=8.6.0.0, Culture=neutral, PublicKeyToken=b439a24ee43b0816

credentialGeneratorClass

Name of the class that implements the com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator interface. This class is used to get credentials for clients. false : no value

credentialGeneratorProps

Properties for the CredentialGenerator implementation class. The properties are set to the object with the setProperties(String) method. The credentialGeneratorprops value is used only if the value of the credentialGeneratorClass property is not null.

Transport layer security configuration properties

transportType

Client transport type. The possible values are:

• TCP/IP: Indicates that the client only supports TCP/IP connections.

• SSL-Supported: Indicates that the client supports both TCP/IP and SSL connections. (false) We cannot use the SSL-supported setting with IBM eXtremeIO (XIO) configurations.

• SSL-Required: Indicates that the client requires SSL connections.

SSL configuration properties

alias

Alias name in the keystore. This property is used if the keystore has multiple key pair certificates and we want to select one of the certificates. no value

contextProvider

Name of the context provider for the trust service. If you indicate a value that is not valid, a security exception results that indicates that the context provider type is incorrect.

Valid values:

IBMJSSE2,
IBMJSSE,
IBMJSSEFIPS, and so on.

keyStore

Fully qualified path to the keystore file.

Example:

etc/test/security/client.private

keyStoreType

Indicates the type of keystore. If you indicate a value that is not valid, a runtime security exception occurs.

Valid values:

JKS,
JCEK,
PKCS12, and so on.

protocol

Indicates the type of security protocol to use for the client. Set this protocol value based on which security provider you use. If you indicate a value that is not valid, a security exception results that indicates that the protocol value is incorrect.

Valid values:

SSL,
SSLv3,
TLS,
TLSv1, and so on.

Valid values:

SSLv2,
SSLv3,
TLS or
Default (SSLv3 or TLS1.0)

publicKeyFile

Fully-qualified path name to a file that contains the exported public key from the server.

Example: c:\tmp\wxs\serverA.cer

trustStoreType

Indicates the type of truststore. If you indicate a value that is not valid, a runtime security exception results.

Valid values:

JKS,
JCEK,
PKCS12, and so on.

trustStore

Fully qualified path to the truststore file.

Example:

etc/test/security/server.public

keyStorePassword

String password to the keystore. We can encode this value or use the actual value.

trustStorePassword

Specifies a string password to the truststore. We can encode this value or use the actual value.

REST data service properties file

To configure the REST data service, edit the properties file for REST and define the required entity schema for a data grid.

The REST data service properties file is the main configuration file for the eXtreme Scale REST data service. This file is a Java property file with key-value pairs. By default, the REST data service runtime environment looks for a well-named wxsRestService.properties file in the classpath. The file can also be explicitly defined using the system property: wxs.restservice.props.

-Dwxs.restservice.props=/usr/configs/dataservice.properties

When the REST data service is loaded, the property file used is displayed in the log files:

CWOBJ4004I: The eXtreme Scale REST data service properties files were loaded: [/usr/configs/RestService.properties]

The REST data service properties file supports the following properties:

Property	Description
catalogServiceEndPoints	The required comma-delimited list of hosts and ports of a catalog service domain in the format: <host:port>. This is optional if using WebSphere Application Server integrated with WebSphere eXtreme Scale to host the REST data service. catalogServiceEndPoints= server1:2809,server2:2809
objectGridNames	The required names of the data grids to expose to the REST service. At least one ObjectGrid name is required. Separate multiple ObjectGrid names using a comma: ECommerceGrid,InventoryGrid
objectGridClientXML	The optional name of the ObjectGrid client override XML file. The name specified here will be loaded from the classpath. The default is: /META-INF/objectGridClient.xml.
ogClientPropertyFile	The optional name of the ObjectGrid client property file. This file contains security properties that are required for enabling ObjectGrid client security. If the "securityEnabled" attribute is set in the property file, security will be enabled on the ObjectGrid client used by the REST service. The "credentialGeneratorProps" must also be set in the property file to a value in the format of "user:pass" or a value of {xor_encoded user:pass}
loginType	The type of authentication used by the REST Service when ObjectGrid client security is enabled. If ObjectGrid client security is not enabled, this property is ignored. If ObjectGrid client security is enabled and loginType is set to basic, the REST service will: Use the credentials specified in the 'credentialGeneratorProps' property of the ObjectGrid client property file for ObjectGrid operations at service initialization. Use HTTP BASIC authentication for per request ObjectGrid session operations If ObjectGrid client security is enabled and loginType is set to none the REST service will: Use the credentials specified in the 'credentialGeneratorProps' property of the ObjectGrid client property file for ObjectGrid operations at service initialization. Use the credentials specified in the 'credentialGeneratorProps' property of the ObjectGrid client property file for per request ObjectGrid session operations.
traceFile	The optional name of the file to redirect the trace output to. The default is logs/trace.log.
traceSpec	The optional trace specification that the eXtreme Scale runtime server should initially use. The default is *=all=disabled. To trace the entire REST data service, use: ObjectGridRest*=all=enabled
verboseOutput	If set to true, REST data service clients receive additional diagnostic information when failures occur. The default is false. This optional value should be set to false for production environments as sensitive information may be revealed.
maxResultsPerCollection	The optional maximum number of results that will be returned in a query. The default value is unlimited. Any positive integer is a valid value.
wxsRestAccessRightsFile	The optional name of the eXtreme Scale REST service access rights property file which specifies the access rights for the service operations and the ObjectGrid entities. If this property is specified, the REST service will try to load the file from the path specified, else it will try to load the file from its classpath.

WebSphere eXtreme Scale configuration

The eXtreme Scale REST data service interacts with WXS using the EntityManager API. An entity schema is defined for a WXS data grid and the metadata for the entities is automatically consumed by the REST data service.

For example, we can define an entity representing a Person in a WXS data grid as follows:

@Entity               
public class Person {
  @Id String taxId;
  String firstName;
  String lastName;}

The annotations used here are in the com.ibm.websphere.projector.annotations package.

The REST service automatically creates an ADO.NET Entity Data Model for Data Services (EDMX) document, which is available using the $metadata URI:

http://localhost:8080/wxsrestservice/restservice/NorthwindGrid/$metadata

After the data grid is configured and running, configure and package a WXS client.

Entity model

WebSphere eXtreme Scale entities are modeled using the entity annotations or an entity metadata descriptor file. The eXtreme Scale REST service uses the entity metadata to automatically create an EDMX model for the data service.

This version of the WebSphere eXtreme Scale REST data service has the following schema restrictions:

• When defining entities in a partitioned data grid, all entities must have a direct or indirect single valued association to the root entity (a key association). The WCF data service client runtime environment must be able to access every entity directly through its canonical address. Therefore, the key of the root entity used for partition routing (the schema root) must be part of the key in the child entity.

  For example:

  @Entity(schemaRoot=true)
  public class Person {
      @Id String taxId;
      String firstName;
      String lastName;
      @OneToMany(mappedBy="person") 
      List<Address> addresses;}
  
  @Entity public class Address {
      @Id int addrId;
      @Id @ManyToOne Person person;
      String street;}

• Bi-directional and uni-directional associations are supported. However, uni-directional associations may not always work from a Microsoft WCF Data Services client since they can only be navigated in one direction and the Microsoft specification requires all associations to be bi-directional.

• Referential constraints are not supported. The WebSphere eXtreme Scale runtime environment does not validate keys between entities. Associations between entities must be managed by the client.

• Complex types are not supported. The EntityManager API does not support embeddable attributes. All attributes are expected to be simple type attributes (see the simple attribute types listed below). Non-simple type attributes are treated as a binary object from the perspective of the client.

• Entity inheritance is not supported. The EntityManager API does not support inheritance.

• Media Resources and Media Links are not supported. The HasStream attribute of the EntityType in the Conceptual Schema Definition Language Document for Data Services is never used.

Mapping between EDM data types and Java data types

The OData protocol defines the following list of Entity Data Model (EDM) types in its abstract type system. The following topics describe how the eXtreme Scale REST adapter chooses the EDM type based on the basic type defined in the entity. For details on EDM types, see: MSDN Library: Abstract Type System .

The following EDM types are available in WCF Data Services:

• Edm.Binary
• Edm.Boolean
• Edm.Byte
• Edm.DateTime
• Edm.Time
• Edm.Decimal
• Edm.Double
• Edm.Single
• Edm.Float
• Edm.Guid *
• Edm.Int16
• Edm.Int32
• Edm.Int64
• Edm.SByte
• Edm.String

The EDM type: Edm.Guid is not supported by the eXtreme Scale REST data service.

Mapping Java types to EDM types

The eXtreme Scale REST data service automatically converts basic entity types into EDM types. The type mapping can be seen by displaying the Entity Data Model Extensions (EDMX) metadata document using the $metadata URI. The EDM type is used by clients to read and write data to the REST data service.

Java Type	EDM Type
boolean java.lang.Boolean	Edm.Boolean
byte java.lang.Byte	Edm.SByte
short java.lang.Short	Edm.Int16
int java.lang.Integer	Edm.Int32
long java.lang.Long	Edm.Int64
float java.lang.Float	Edm.Single
double java.lang.Double	Edm.Double
java.math.BigDecimal	Edm.Decimal
java.math.BigInteger	java.math.BigInteger
java.lang.String	Edm.String
char	char
java.lang.Character	java.lang.Character
Char[]	Char[]
java.lang.Character[]	java.lang.Character[]
java.util.Calendar	Edm.DateTime
java.util.Date	java.util.Date
java.sql.Date	java.sql.Date
java.sql.Timestamp	java.sql.Timestamp
java.sql.Time	java.sql.Time
Other types	Edm.Binary

Mapping from EDM types to Java types

For Update requests and Insert requests, the payload specifies the data to be updated or inserted into the eXtreme Scale REST data service. The service can automatically convert compatible data types to the data types defined in the EDMX document. The REST data service converts the XML encoded string representations of the value into the correct type using the following two-step process:

1. A type check is performed to make sure the EDM type is compatible with the Java type. An EDM type is compatible with a Java type if the data supported by the EDM type is a subset of the data supported by the Java type. For example, Edm.int32 type is compatible with a Java long type, but Edm.int32 type is not compatible with a Java short type.

2. A target Java type object will be created which represents the string value in the payload.

EDM Type	Java Type
Edm.Boolean	boolean java.lang.Boolean
Edm.SByte	byte java.lang.Byte short java.lang.Short int java.lang.Integer long java.lang.Long float java.lang.Float double java.lang.Double java.math.BigDecimal java.math.BigInteger char java.lang.Character
Edm.Byte, Edm.Int16	short java.lang.Short int java.lang.Integer long java.lang.Long float java.lang.Float double java.lang.Double java.math.BigDecimal java.math.BigInteger char java.lang.Character
Edm.Int32	int java.lang.Integer long java.lang.Long float java.lang.Float double java.lang.Double java.math.BigDecimal java.math.BigInteger
Edm.Int64	long java.lang.Long double java.lang.Double java.math.BigDecimal java.math.BigInteger
Edm.Double	double java.lang.Double java.math.BigDecimal
Edm.Decimal	double java.lang.Double java.math.BigDecimal java.math.BigInteger
Edm.Single	float java.lang.Float double java.lang.Double java.math.BigDecimal
Edm.String	java.lang.String char java.lang.Character Char[] java.lang.Character[] java.math.BigDecimal java.math.BigInteger
Edm.DateTime	java.util.Calendar java.util.Date java.sql.Date java.sql.Time java.sql.Timestamp
Edm.Time	java.sql.Time java.sql.Timestamp

Mapping temporal types

Java includes five temporal types for storing date, time or both: java.util.Date, java.sql.Date, java.sql.Time, java.sql.Timestamp and java.util.Calendar. All of these types are expressed in the entity data model as Edm.DateTime. The eXtreme Scale REST data service automatically converts and normalizes the data depending on the Java type. This topic describes several issues that developers must be aware of when using any temporal type.

Time zone differences

In WCF Data Services, the descriptions of time values in the Edm.DateTime type are always expressed using the Coordinated Universal Time (UTC) standard, which is the internationally recognized name for Greenwich Mean Time (GMT). Coordinated Universal Time is the time as measured at zero degrees longitude, the UTC origin point. Daylight saving time is not applicable to UTC.

Converting between entity and EDM types

When a client sends a request to the REST data service, the date and time is represented as a GMT time zone time, like the following example:

"2000-02-29T21:30:30.654123456"

The REST data service will then construct the appropriate Java temporal type instance and insert it into the entity in the data grid.

When a client requests a property which is a Java temporal type from the eXtreme Scale REST data service, the value is always normalized as a GMT time zone value. For example, if an entity java.util.Date is constructed as follows:

Calendar c = Calendar.getInstance();
c.clear();         
c.set(2000, 1, 29, 21, 30, 30);
Date d = c.getTime();

The date and time are represented using the default time zone of the Java process because Calendar.getInstance() will create a Calendar object with local time zone. If the local time zone is CST, then the date, when retrieved from the REST data service will be the GMT representation of the time:

"2000-03-01T03:30:30"

java.sql.Date normalization

An eXtreme Scale entity can define an attribute with Java type java.sql.Date. This data type does not include the time and is normalized by the REST data service. This means that the eXtreme Scale runtime environment does not store any hours, minutes, seconds, or milliseconds information in the java.sql.Date attribute. Regardless of the time zone offset, the date is always represented as a local date.

For example, if the client updates a java.sql.Date property with the value .2009-01-01T03:00:00., the REST data service, which is in the CST time zone (-06:00), will simply create a java.sql.Date instance of which the time is set to .2009-01-01T00:00:00. of the local CST time. There is no time zone conversion done to create the java.sql.Date value. When the REST service client retrieves the value of this attribute, it will be displayed as .2009-01-01T00:00:00Z.. If a time zone conversion were done, the value would be displayed as having the date of .2008-12-31., which would be incorrect.

java.sql.Time normalization

Similar to java.sql.Date, the java.sql.Time values are normalized and do not include date information. This means that the eXtreme Scale run time does not store the year, month or day. The time is stored using the GMT time from the epoch January 1, 1970, which is consistent with the java.sql.Time implementation.

If the client updates a java.sql.Time property with the value "2009-01-01T03:00:00", the REST data service, will create a java.sql.Time instance with the milliseconds set to 3*60*60*1000, which is equal to 3 hours. When the rest service retrieves the value, it will be displayed as "1970-01-01:03:00:00Z".

Associations

Associations define the relationship between two peer entities. The eXtreme Scale REST service reflects the associations modeled with entities defined with WXS annotated entities or entities defined using an entity descriptor XML file.

Association maintenance

The eXtreme Scale REST data service does not support referential integrity constraints. The client should ensure that references are updated when entities are removed or added. If a target entity of an association is removed from the data grid, but the link between the source and target entity is not removed, then the link is broken. The eXtreme Scale REST data service and EntityManager API tolerates broken links and logs the broken links as CWPRJ1022W warnings. Broken associations are removed from the request payload.

Use a batch request to group association updates in a single transaction to avoid broken links.

The ADO.NET Entity Data Model ReferentialConstraint element is not used by the eXtreme Scale REST data service.

Association multiplicity

Entities can have multi-valued associations or single-valued associations. Multi-valued associations, or collections, are one-to-many or many-to-many associations. Single-valued associations are one-to-one or many-to-one associations.

In a partitioned data grid, all entities should have a single-valued key-association path to a root entity. Another section of this topic shows how to define a key association. Because the root entity is used to partition the entity, many-to-many associations are not allowed for partitioned data grids. For an example on how to model a relational entity schema for a partitioned data grid, see Scalable data model in eXtreme Scale .

The following example describes how the EntityManager API association types, modeled using annotated Java classes map to the ADO.NET Entity Data Model:

@Entity public class Customer {
    @Id String customerId;
    @OneToOne TaxInfo taxInfo;
    @ManyToOne Address homeAddress;
    @OneToMany Collection<Order> orders;
    @ManyToMany Collection<SalesPerson> salespersons;}

<Association Name="Customer_TaxInfo">
    <End Type="Model1.Customer" Role="Customer" Multiplicity="1" />
    <End Type="Model1.TaxInfo " Role="TaxInfo" Multiplicity="1" />
</Association>
<Association Name="Customer_Address">
    <End Type="Model1.Customer" Role="Customer" Multiplicity="1" />
    <End Type="Model1.Address" Role="TaxInfo" Multiplicity="*" />
</Association>
<Association Name="Customer_Order">
    <End Type="Model1.Customer" Role="Customer" Multiplicity="*" />
    <End Type="Model1.Order" Role="TaxInfo" Multiplicity="1" />
</Association>
<Association Name="Customer_SalesPerson">
    <End Type="Model1.Customer" Role="Customer" Multiplicity="*" />
    <End Type="Model1.SalesPerson" Role="TaxInfo" Multiplicity="*" />
</Association>

Bi-directional and uni-directional associations

Entities associations can be uni-directional or bi-directional. By specifying the "mappedBy" attribute on the @OneToOne, @OneToMany or @ManyToMany annotation or the "mapped-by" attribute on the one-to-one, one-to-many or many-to-many XML attribute tag, the entity becomes bi-directional. The OData protocol currently requires all entities to be bi-directional, allowing clients to generate navigation paths in both directions. The eXtreme Scale EntityManager API allows modeling uni-directional associations which can save memory and simplify maintenance of the associations. If a uni-directional association is used, the REST data services client must only navigate through the association using the defined association.

For example: If a uni-directional many-to-one association is defined between Address and Country, the following URI is not allowed:

/restservice/CustomerGrid/Country('USA')/addresses

Key associations

Single-valued associations (one-to-one and many-to-one) can also be included as all or part of the entities key. This is known as a key-association.

Key associations are required when using a partitioned data grid. The key association must be defined for all child entities in a partitioned entity schema. The OData protocol requires that all entities are directly addressable. This means that the key in the child entity must include the key used for partitioning.

In the following example, Customer has a one-to-many association to Order. The Customer entity is the root entity and the customerId attribute is used to partition the entity. Order has included the Customer as part of its identity:

@Entity(schemaRoot="true")
public class Customer {
    @Id String customerId;
    @OneToMany(mappedBy="customer") Order orders}

@Entity public class Order {
    @Id int orderId;
    @Id @ManyToOne Customer customer;
    java.util.Date orderDate;}

When the REST data service generates the EDMX document for this model, the Customer key fields are automatically included as part of the Order entity:

<EntityType Name="Order">
<Key>
    <PropertyRef Name="orderId"/>
    <PropertyRef Name="customer_customerId"/>
</Key>

<Property Name="orderId" Type="Edm.Int64" Nullable="false"/>
<Property Name="customer_customerId" Type="Edm.String" 
    Nullable="false"/>
<Property Name="orderDate" Type="Edm.DateTime" Nullable="true"/>
<NavigationProperty Name="customer" 
    Relationship="NorthwindGridModel.Customer_orders"
    FromRole="Order" ToRole="Customer"/>

<NavigationProperty Name="orderDetails" 
    Relationship="NorthwindGridModel.Order_orderDetails" 
    FromRole="Order" ToRole="OrderDetail"/>
</EntityType>

When an entity is created, the key must never change. This means if the key association between a child entity and its parent must change, the child entity must be removed and re-created with a different parent. In a partitioned data grid, this will require two different batch change sets since the move will likely involve more than one partition.

Cascading operations

The EntityManager API allows a flexible cascade policy. Associations can be marked to cascade a persist, remove, invalidate or merge operation. Such cascade operations can happen on one or both sides of a bi-directional association.

The OData protocol only allows cascade delete operations on the single-side of the association. The CascadeType.REMOVE annotation or cascade-remove XML attribute cannot be defined on both sides of a one-to-one bi-directional association or on the many-side of a one-to-many association. The following example illustrates a valid Cascade.REMOVE bi-directional association:

@Entity(schemaRoot="true")
public class Customer {
    @Id String customerId;
    @OneToMany(mappedBy="customer", cascade=CascadeType.REMOVE)
    Order orders}

@Entity public class Order {
    @Id int orderId;
    @Id @ManyToOne Customer customer;
    java.util.Date orderDate;}

The resulting EDMX association looks as follows:

<Association Name="Customer_orders">
    <End Type="NorthwindGridModel.Customer" Role="Customer" 
        Multiplicity="1">
        <OnDelete Action="Cascade"/>
    </End>
    <End Type="NorthwindGridModel.Order" Role="Order" 
        Multiplicity="*"/>
</Association>

ObjectGrid descriptor XML file

To configure WebSphere eXtreme Scale, use an ObjectGrid descriptor XML file and the ObjectGrid API.

In the following sections, sample XML files are provided to illustrate various configurations. Each element and attribute of the XML file is defined. Use the ObjectGrid descriptor XML schema to create the descriptor XML file.

A modified version of the original companyGrid.xml file is used. The following companyGridSingleMap.xml file is like the companyGrid.xml file. The companyGridSingleMap.xml file has one map, and the companyGrid.xml file has four maps. The elements and attributes of the file are described in detail following the example.

<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
  xmlns="http://ibm.com/ws/objectgrid/config">

  <objectGrids>
    <objectGrid name="CompanyGrid">
      <backingMap name="Customer"/>
    </objectGrid>
  </objectGrids>
</objectGridConfig>

objectGridConfig element

The objectGridConfig element is the top-level element of the XML file. Write this element in your eXtreme Scale XML document as shown in the preceding example. This element sets up the namespace of the file and the schema location. The schema is defined in the objectGrid.xsd file.

• Number of occurrences: One
• Child element: objectGrids element and backingMapPluginCollections element

objectGrids element

The objectGrids element is a container for all the objectGrid elements. In the companyGridSingleMap.xml file, the objectGrids element contains one objectGrid, the CompanyGrid objectGrid.

• Number of occurrences: One or more
• Child element: objectGrid element

objectGrid element

Use the objectGrid element to define an ObjectGrid. Each of the attributes on the objectGrid element corresponds to a method on the ObjectGrid interface.

• Number of occurrences: One to many
• Child element: bean element, backingMap element, and querySchema element

Attributes

name

Name that is assigned to ObjectGrid. The XML validation fails if this attribute is missing. (Required)

securityEnabled

Enables security at the ObjectGrid level, which enables the access authorizations to the data in the map, when you set the attribute to true. The default is true. (Optional)

authorizationMechanism

Set the authorization mechanism for the element. We can set the attribute to one of two values:

AUTHORIZATION_MECHANISM_JAAS or AUTHORIZATION_MECHANISM_CUSTOM. The default is

AUTHORIZATION_MECHANISM_JAAS. Set the securityEnabled attribute to true for the authorizationMechanism attribute to take effect. (Optional)

permissionCheckPeriod

Specifies an integer value in seconds that indicates how often to check the permission used to allow a client access. The default is

0. When you set the attribute value

0, every get, put, update, remove, or evict method call asks the authorization mechanism, either Java Authentication and Authorization Service (JAAS) authorization or custom authorization, to check if the current subject has permission. A value greater than 0 indicates the number of seconds to cache a set of permissions before returning to the authorization mechanism to refresh. Set the securityEnabled attribute to true for the permissionCheckPeriod attribute to take effect. (Optional)

Note: The upsert and upsertAll methods replace the ObjectMap put and putAll methods. Use the upsert method to tell the BackingMap and loader that an entry in the data grid needs to place the key and value into the grid. The BackingMap and loader does either an insert or an update to place the value into the grid and loader. If we run the upsert API within the applications, then the loader gets an UPSERT LogElement type, which allows loaders to do database merge or upsert calls instead of using insert or update.

accessByCreatorOnlyMode

Specifies if a user (represented by the Principal objects associated with it) other than the creator of a cache entry can access, update or delete that entry. The default value is

disabled when not specified, allowing any user access to the cache entry. Valid values also include

complement and

supersede. The complement value enables creator-only access, and also enforces map authorization. The supersede value enables creator-only access, and disables map authorization. (Optional)

txTimeout

Amount of time in seconds that a transaction is allowed for completion. If a transaction does not complete in this amount of time, the transaction is marked for rollback and a TransactionTimeoutException exception results. If you set the value to 0, the default setting of 10 minutes is used as the transaction timeout. (Optional)

entityMetadataXMLFile

Path to the entity descriptor XML file that defines the entity schema. Define entities before you start the catalog server so that each entity can bind with a backing map.

• For a relative directory: Specify the location relative to the location of the objectgrid.xml file.

• For an absolute path: Specify the location with a URL format, such as file:// or http://.

(Optional)

<objectGrid (1) name="objectGridName"
(2) securityEnabled="true" | "false"
(3) authorizationMechanism="AUTHORIZATION_MECHANISM_JASS" | "AUTHORIZATION_MECHANISM_CUSTOM"
(4)  permissionCheckPeriod="permission_check_period"
(5) txTimeout="seconds"
(6) entityMetadataXMLFile="URL"
/>

In the following example, the companyGridObjectGridAttr.xml file demonstrates one way to configure the attributes of an objectGrid element. Security is enabled, the authorization mechanism is set to JAAS, and the permission check period is set to 45 seconds. The file also registers entities by specifying an entityMetadataXMLFile attribute.

<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlnc:xsi="http:www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
 xmlns="http://ibm.com/ws/objectgrid/config">

 <objectGrids>
  <objectGrid name="CompanyGrid" securityEnabled="true"
   authorizationMechanism="AUTHORIZATION_MECHANISM_JASS"
   permissionCheckPeriod="45"
   entityMetadataXMLFile="companyGridEntities.xml">
   <backingMap name="Customer"/>
  </objectGrid>
 </objectGrids>
</objectGridConfig>

The following code sample demonstrates the programmatic approach to achieving the same configuration as the companyGridObjectGridAttr.xml file in the preceding example.

ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);

companyGrid.setSecurityEnabled();
companyGrid.setAuthorizationMechanism(SecurityConstants.AUTHORIZATION_MECHANISM_JAAS);
companyGrid.setPermissionCheckPeriod(45);
companyGrid.registerEntities(new URL("file:companyGridEntities.xml"));

backingMap element

The backingMap element is used to define a BackingMap instance on an ObjectGrid. Each of the attributes on the backingMap element corresponds to a method on the BackingMap interface.

• Number of occurrences: Zero to many
• Child element: timeBasedDBUpdate element

backingMap attributes

copyKey

Specifies if the a copy of the key is required when a map entry is created. Copying the key object allows the application to use the same key object for each ObjectMap operation. Set true to copy the key object when a map entry is created. The default value is false. (Optional)

CopyMode

Specifies if a get operation of an entry in the BackingMap instance returns the actual value, a copy of the value, or a proxy for the value. Set the CopyMode attribute to one of five values:

COPY_ON_READ_AND_COMMIT

The default value is

COPY_ON_READ_AND_COMMIT. Set the value to COPY_ON_READ_AND_COMMIT to ensure that an application never has a reference to the value object that is in the BackingMap instance. Instead, the application is always working with a copy of the value that is in the BackingMap instance. (Optional)

COPY_ON_READ

Set the value to COPY_ON_READ to improve performance over the COPY_ON_READ_AND_COMMIT value by eliminating the copy that occurs when a transaction is committed. To preserve the integrity of the BackingMap data, the application commits to delete every reference to an entry after the transaction is committed. Setting this value results in an ObjectMap.get method returning a copy of the value instead of a reference to the value, which ensures changes that are made by the application to the value does not affect the BackingMap element until the transaction is committed.

COPY_ON_WRITE

Set the value to COPY_ON_WRITE to improve performance over the COPY_ON_READ_AND_COMMIT value by eliminating the copy that occurs when ObjectMap.get method is called for the first time by a transaction for a given key. Instead, the ObjectMap.get method returns a proxy to the value instead of a direct reference to the value object. The proxy ensures that a copy of the value is not made unless the application calls a set method on the value interface.

NO_COPY

Set the value to NO_COPY to allow an application to never modify a value object that is obtained using an ObjectMap.get method in exchange for performance improvements. Set the value to NO_COPY for maps associated with EntityManager API entities.

COPY_TO_BYTES

Set the value to COPY_TO_BYTES to improve memory footprint for complex Object types and to improve performance when the copying of an Object relies on serialization to make the copy. If an Object is not Cloneable or a custom ObjectTransformer with an efficient copyValue method is not provided, the default copy mechanism is to serialize and inflate the object to make a copy. With the COPY_TO_BYTES setting, inflate is only performed during a read and serialize is only performed during commit.

For more information about these settings, see Tuning the copy mode .

evictionTriggers

Types of additional eviction triggers to use. All evictors for the backing map use this list of additional triggers. To avoid an IllegalStateException, this attribute must be called before the ObjectGrid.initialize() method. Also, note that the ObjectGrid.getSession() method implicitly calls the ObjectGrid.initialize() method if the method has yet to be called by the application. Entries in the list of triggers are separated by semicolons. Current eviction triggers include MEMORY_USAGE_THRESHOLD. For more information, see Plug-ins for evicting cache objects . (Optional)

lockStrategy

Specifies if the internal lock manager is used whenever a map entry is accessed by a transaction. Set this attribute to one of three values:

OPTIMISTIC,

PESSIMISTIC, or NONE. The default value is

OPTIMISTIC. (Optional)

The optimistic locking strategy is typically used when a map does not have a loader plug-in, is mostly read and not frequently written to or updated, and the locking is not provided by the persistence manager using eXtreme Scale as a side cache or by the application. An exclusive lock is obtained on a map entry that is inserted, updated, or removed at commit time. The lock ensures that the version information cannot be changed by another transaction while the transaction being committed is performing an optimistic version check.

The pessimistic locking strategy is typically used for a map that does not have a loader plug-in, and locking is not provided by a persistence manager using eXtreme Scale as a side cache, by a loader plug-in, or by the application. The pessimistic locking strategy is used when the optimistic locking strategy fails too often because update transactions frequently collide on the same map entry.

The no locking strategy indicates that the internal LockManager is not needed. Concurrency control is provided outside of eXtreme Scale, either by the persistence manager using eXtreme Scale as a side cache or application, or by the loader plug-in that uses database locks to control concurrency.

For more information, see Lock manager .

lockTimeout

Set the lock timeout used by the lock manager for the BackingMap instance. Set the lockStrategy attribute to OPTIMISTIC or PESSIMISTIC to create a lock manager for the BackingMap instance. To prevent deadlocks from occurring, the lock manager has a default timeout value of 15 seconds. If the timeout limit is exceeded, a LockTimeoutException exception occurs. The default value of 15 seconds is sufficient for most applications, but on a heavily loaded system, a timeout might occur when no deadlock exists. Use the lockTimeout attribute to increase the value from the default to prevent false timeout exceptions from occurring. Set the lockStrategy attribute to NONE to specify the BackingMap instance use no lock manager. (Optional)

name

Name that is assigned to the backingMap instance. If this attribute is missing, the XML validation fails. (Required)

nearCacheEnabled

Set true to enable the client local cache. To use a near cache, the lockStrategy attribute must be set to NONE or OPTIMISTIC. true (Optional)

nearCacheInvalidationEnabled

Set true to enable the removal of stale data from the near cache as quickly as possible. Any update, deletion, or invalidation operation against the data grid triggers an asynchronous invalidation in the near cache. Because the invalidation is asynchronous, client applications might access stale data for a short time period after an update has occurred before the stale value is removed from the near cache. To use near cache invalidation, the lockStrategy attribute must be set to NONE or OPTIMISTIC. false (Optional)

nearCacheLastAccessTTLSyncEnabled

Set true to enable time-to-live (TTL) information to be synchronized with the remote data grid. The LAST_ACCESS_TIME TTL evictor type must be enabled when you enable this property. (Optional)

nullValuesSupported

Set true to support null values in the ObjectMap. When null values are supported, a get operation that returns null might mean that the value is null or that the map does not contain the key that is passed to the method. Default is true. (Optional)

numberOfBuckets

Deprecated: This property has been deprecated. Use the nearCacheEnabled attribute to enable the near cache. Number of buckets for the BackingMap instance to use. The BackingMap instance uses a hash map for implementation. If multiple entries exist in the BackingMap, more buckets lead to better performance because the risk of collisions is lower as the number of buckets increases. More buckets also lead to more concurrency. Specify a value of

0 to disable the near cache on a client. When you set the value to 0 for a client, set the value in the client override ObjectGrid XML descriptor file only. (Optional)

numberOfLockBuckets

Set the number of lock buckets used by the lock manager for the BackingMap instance. Set the lockStrategy attribute to OPTIMISTIC or PESSIMISTIC to create a lock manager for the BackingMap instance. The lock manager uses a hash map to track entries that are locked by one or more transactions. If many entries exist, more lock buckets lead to better performance because the risk of collisions is lower as the number of buckets grows. More lock buckets also lead to more concurrency. Set the lockStrategy attribute to NONE to specify the BackingMap instance use no lock manager. (Optional)

pluginCollectionRef

Specifies a reference to a backingMapPluginCollection plug-in. The value of this attribute must match the ID attribute of a backingMapCollection plug-in. Validation fails if no matching ID exists. Set the attribute to reuse BackingMap plug-ins. (Optional)

preloadMode

Set the preload mode if a loader plug-in is set for this BackingMap instance. The default value is false. If the attribute is set to true, the Loader.preloadMap(Session, BackingMap) method is invoked asynchronously. Otherwise, running the method is blocked when loading data so that the cache is unavailable until preload completes. Preloading occurs during initialization. (Optional)

readOnly

Set a BackingMap instance as read/write when you specify the attribute as false. When you specify the attribute as true, the BackingMap instance is read-only. (Optional)

template

Specifies if dynamic maps can be used. Set this value to true if the BackingMap map is a template map. Template maps can be used to dynamically create maps after the ObjectGrid is started. Calls to Session.getMap(String) result in dynamic maps being created if the name passed to the method matches the regular expression specified in the name attribute of the backingMap. The default value is false. (Optional)

timeToLive

Specifies in seconds how long each map entry is present. The default value of

0 means that the map entry is present forever, or until the application explicitly removes or invalidates the entry. Otherwise, the TTL evictor evicts the map entry based on this value. (Optional)

ttlEvictorType

Specifies how the expiration time of a BackingMap entry is computed. Set this attribute to one of these values:

CREATION_TIME,

LAST_ACCESS_TIME,

LAST_UPDATE_TIME, or NONE. The CREATION_TIME value indicates that an entry expiration time is the sum of the creation time of the entry plus the timeToLive attribute value. The LAST_ACCESS_TIME value indicates that an entry expiration time is the sum of the last access time of the entry (whether the entry was updated or merely read), plus the timeToLive attribute value. The LAST_UPDATE_TIME value indicates that an entry expiration time is the sum of the last update time of the entry plus the timeToLive attribute value. The NONE value, which is the default, indicates that an entry has no expiration time and is present in the BackingMap instance until the application explicitly removes or invalidates the entry. (Optional)

valueInterfaceClassName

Specifies a class that is required when you set the CopyMode attribute to COPY_ON_WRITE. This attribute is ignored for all other modes. The COPY_ON_WRITE value uses a proxy when ObjectMap.get method calls are made. The proxy ensures that a copy of the value is not made unless the application calls a set method on the class specified as the valueInterfaceClassName attribute. (Optional)

viewRef

Specifies that the backingMap is a view map. (Optional)

writeBehind

Specifies that the write-behind support is enabled with write-behind parameters (Optional). Write-behind parameters consist of a maximum update time and a maximum key update count. The format of the write-behind parameter is

"[T(time)][;][C(count)]". The database is updated when one of the following events occurs:

• The maximum update time, specified in seconds, has passed since the last update.
• The number of available updates in the queue map has reached the maximum update count.

For more information, see Write-behind caching .

Write-behind support is an extension of the Loader plug-in, which you use to integrate eXtreme Scale with the database. For example, consult the Configuring JPA loaders information about configuring a JPA loader.

<backingMap (1)   name="objectGridName"
(2)   readOnly="true" | "false"
(3)   template="true" | "false"
(4)   pluginCollectionRef="reference to backingMapPluginCollection"
(5)   numberOfBuckets="number of buckets"
(6)   preloadMode="true" | "false"
(7)   lockStrategy="OPTIMISTIC" | "PESSIMISTIC" | "NONE"
(8)   numberOfLockBuckets="number of lock buckets"
(9)   lockTimeout="lock timeout"
(10)   copyMode="COPY_ON_READ_AND_COMMIT" | "COPY_ON_READ" | "COPY_ON_WRITE"
       | "NO_COPY" | "COPY_TO_BYTES"
(11)   valueInterfaceClassName="value interface class name"
(12)   copyKey="true" | "false"
(13)   nullValuesSupported="true" | "false"
(14)   ttlEvictorType="CREATION_TIME" | "LAST_ACCESS_TIME" | "LAST_UPDATE_TIME" | NONE"
(15)   timeToLive="time to live"
(16)   streamRef="reference to a stream"
(17)   viewRef="reference to a view"
(18)   writeBehind="write-behind parameters"
(19)   nearCacheEnabled="true" | "false"
(20)   nearCacheInvalidationEnabled="true" | "false"
(21)   nearCacheLastAccessTTLSyncEnabled="true" | "false"/>  

In the following example, the companyGridBackingMapAttr.xml file is used to demonstrate a sample backingMap configuration.

<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
 xmlns="http://ibm.com/ws/objectgrid/config">

 <objectGrids>
  <objectGrid name="CompanyGrid">
    <backingMap name="Customer" readOnly="true"
     numberOfBuckets="641" preloadMode="false"
     lockStrategy="OPTIMISTIC" numberOfLockBuckets="409"
     lockTimeout="30" copyMode="COPY_ON_WRITE"
     valueInterfaceClassName="com.ibm.websphere.samples.objectgrid.CounterValueInterface"
     copyKey="true" nullValuesSupported="false"
     ttlEvictorType="LAST_ACCESS_TIME" timeToLive="3000"/>
  </objectGrid>
 </objectGrids>
</objectGridConfig>

The following sample code demonstrates the programmatic approach to achieve the same configuration as the companyGridBackingMapAttr.xml file in the preceding example:

ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);

BackingMap customerMap = companyGrid.defineMap("Customer");
customerMap.setReadOnly(true);
customerMap.setNumberOfBuckets(641);
customerMap.setPreloadMode(false);
customerMap.setLockStrategy(LockStrategy.OPTIMISTIC);
customerMap.setNumberOfLockBuckets(409);
customerMap.setLockTimeout(30);

// when setting copy mode to COPY_ON_WRITE, a valueInterface class is required customerMap.setCopyMode(CopyMode.COPY_ON_WRITE, 
 com.ibm.websphere.samples.objectgrid.CounterValueInterface.class);
customerMap.setCopyKey(true);
customerMap.setNullValuesSupported(false);
customerMap.setTtlEvictorType(TTLType.LAST_ACCESS_TIME);
customerMap.setTimeToLive(3000); 
// set time to live to 50 minutes

bean element

Use the bean element to define plug-ins. We can attach plug-ins to objectGrid and BackingMap elements.

• Number of occurrences within the objectGrid element: Zero to many
• Number of occurrences within the backingMapPluginCollection element: Zero to many
• Child element: property element

Attributes

id

Type of plug-in to create. (Required)

The valid plug-ins for a bean that is a child element of the objectGrid element are included in the following list:

• TransactionCallback plug-in
• ObjectGridEventListener plug-in
• SubjectSource plug-in
• SubjectValidation plug-in

The valid plug-ins for a bean that is a child element of the backingMapPluginCollection element are included in the following list:

• Loader plug-in
• ObjectTransformer plug-in
• OptimisticCallback plug-in
• Evictor plug-in
• MapEventListener plug-in
• MapIndex plug-in

className

Name of the class or spring bean to instantiate to create the plug-in. The class must implement the plug-in type interface. For example, if you specify

ObjectGridEventListener as the value for the id attribute, the className attribute value must refer to a class that implements the ObjectGridEventListener interface. The className or osgiService is required.

osgiService

Name of the OSGi service to look up in the OSGi service manager. When running in the Eclipse Equinox OSGi framework with the Eclipse Gemini or Apache Aries Blueprint container, plug-ins can be defined using an OSGi Blueprint XML file. The other bean properties are not typically used when using an osgiService name, since the bean properties are configured in the Blueprint configuration file. The className or osgiService is required.

<bean (1) id="TransactionCallback" | "ObjectGridEventListener" |"SubjectSource" |
     "SubjectValidation" | "Loader" | "ObjectTransformer" |
    "OptimisticCallback" | "Evictor" | "MapEventListener" | "MapIndexPlugin"
(2) className="class name" | "(spring)bean name"
/>

In the following example, the companyGridBean.xml file is used to demonstrate how to configure plug-ins using the bean element. An ObjectGridEventListener plug-in is added to the CompanyGrid ObjectGrid. The className attribute for this bean is the com.ibm.websphere.objectgrid.plugins.builtins.TranPropListener class. This class implements the com.ibm.websphere.objectgrid.plugins.ObjectGridEventListener interface as required.

A BackingMap plug-in is also defined in the companyGridBean.xml file. An evictor plug-in is added to the Customer BackingMap instance. Because the bean ID is Evictor, the className attribute must specify a class that implements the com.ibm.websphere.objectgrid.plugins.Evictor interface. The com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor class implements this interface. The backingMap references its plug-ins using the pluginCollectionRef attribute.

<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
 xmlns="http://ibm.com/ws/objectgrid/config">

 <objectGrids>
  <objectGrid name="CompanyGrid">
   bean id="ObjectGridEventListener"
    className="com.ibm.websphere.objectgrid.plugins.builtins.TranPropListener"/>
   <backingMap name="Customer"
    pluginCollectionRef="customerPlugins"/>
  </objectGrid>
 </objectGrids>
 <backingMapPluginCollections>
  <backingMapPluginCollection id="customerPlugins">
   <bean id="Evictor"
     className="com.ibm.websphere.objectGrid.plugins.builtins.LRUEvictor/>
  </backingMapPluginCollection>
 </backingMapPluginCollections>
</objectGridConfig>

The following code sample demonstrates the programmatic approach to achieving the same configuration as the companyGridBean.xml file in the preceding example.

ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);
TranPropListener tranPropListener = new TranPropListener();
companyGrid.addEventListener(tranPropListener);

BackingMap customerMap = companyGrid.defineMap("Customer");
Evictor lruEvictor = new com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor();
customerMap.setEvictor(lruEvictor);

For more details about using plug-ins, consult Java plug-ins overview .

property element

Use the property element to add properties to plug-ins. The name of the property must correspond to a set method on the class referenced by the containing bean.

• Number of occurrences: Zero to many
• Child element: None

Attributes

name

Name of the property. The value that is assigned to this attribute must correspond to a set method on the class that is provided as the className attribute on the containing bean. For example, if you set the className attribute of the bean to com.ibm.MyPlugin, and the name of the property that is provided is

size, the com.ibm.MyPlugin class must have a setSize method. (Required)

type

Type of the property. The type is passed to the set method that is identified by the name attribute. The valid values are the Java primitives, the java.lang counterparts, and java.lang.String. The name and type attributes must correspond to a method signature on the className attribute of the bean. For example, if you set the name as

size and the type as

int, a setSize(int) method must exist on the class specified as the className attribute for the bean. (Required)

value

Specifies the value of the property. This value is converted to the type specified by the type attribute, and is then used as a parameter in the call to the set method that is identified by the name and type attributes. The value of this attribute is not validated in any way. (Required)

description

Describes the property. (Optional)

<bean (1) name="name"
(2) type="java.lang.String" | "boolean" | "java.lang.Boolean" | "int" |
    "java.lang.Integer" | "double" | "java.lang.Double" | "byte" |
    "java.lang.Byte" | "short" | "java.lang.Short" | "long" | 
    "java.lang.Long" | "float" | "java.lang.Float" | "char" | 
    "java.lang.Character"
(3) value="value"
(4) description="description"
/>

In the following example, the companyGridProperty.xml file is used to demonstrate how to add a property element to a bean. In this example, a property with the name maxSize and type int is added to an evictor. The com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor class has a method signature that matches the setMaxSize(int) method. An integer value of 499 is passed to the setMaxSize(int) method on the com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor class.

<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
 xmlns="http://ibm.com/ws/objectgrid/config">

 <objectGrids>
  <objectGrid name="CompanyGrid">
   <backingMap name="Customer"
    pluginCollectionRef="customerPlugins"/>
  </objectGrid>
 </objectGrids>
 <backingMapPluginCollections>
  <backingMapPluginCollection id="customerPlugins">
   <bean id="Evictor"
     className="com.ibm.websphere.objectGrid.plugins.builtins.LRUEvictor>
     <property name="maxSize" type="int" value="449"
       description="The maximum size of the LRU Evictor"/>
   </bean>
  </backingMapPluginCollection>
 </backingMapPluginCollections>
</objectGridConfig>

The following code sample demonstrates the programmatic approach to achieving the same configuration as the companyGridProperty.xml file in the preceding example.

ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);

BackingMap customerMap = companyGrid.defineMap("Customer");

LRUEvictor lruEvictor = new com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor();
// if the XML file is used instead, 
// the property that was added would cause the following call to occur lruEvictor.setMaxSize(449);
customerMap.setEvictor(lruEvictor);

backingMapPluginsCollections element

The backingMapPluginsCollections element is a container for all the backingMapPluginCollection elements. In the companyGridProperty.xml file in the preceding section, the backingMapPluginCollections element contains one backingMapPluginCollection element with the ID

customerPlugins.

• Number of occurrences: Zero to one
• Child element: backingMapPluginCollection element

backingMapPluginCollection element

The backingMapPluginCollection element defines the BackingMap plug-ins, and is identified by the id attribute. Specify the pluginCollectionRef attribute to reference the plug-ins. When configuring several BackingMaps plug-ins similarly, each BackingMap can reference the same backingMapPluginCollection element.

• Number of occurrences: Zero to many
• Child element: bean element

Attributes

id

Identifies the backingMapPluginCollection, and is referenced by the pluginCollectionRef attribute of the backingMap element. Each ID must be unique. If the value of a pluginCollectionRef attribute does not match the ID of one backingMapPluginCollection element, XML validation fails. Any number of backingMap elements can reference a single backingMapPluginCollection element. (Required)

<backingMapPluginCollection (1)   id="id"
/>

In the following example, the companyGridCollection.xml file is used to demonstrate how to use the backingMapPluginCollection element. In this file, the Customer BackingMap uses the customerPlugins backingMapPluginCollection to configure the Customer BackingMap with an LRUEvictor. The Item and OrderLine BackingMaps reference the collection2 backingMapPluginCollection. These BackingMaps each have an LFUEvictor set.

<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
 xmlns="http://ibm.com/ws/objectgrid/config">

 <objectGrids>
  <objectGrid name="CompanyGrid">
   <backingMap name="Customer"
    pluginCollectionRef="customerPlugins"/>
   <backingMap name="Item" pluginCollectionRef="collection2"/>
   <backingMap name="OrderLine"
    pluginCollectionRef="collection2"/>
   <backingMap name="Order"/>
  </objectGrid>
 </objectGrids>
 <backingMapPluginCollections>
  <backingMapPluginCollection id="customerPlugins">
   <bean id="Evictor"
     className="com.ibm.websphere.objectGrid.plugins.builtins.LRUEvictor/>
  </backingMapPluginCollection>
  <backingMapPluginCollection id="collection2">
   <bean id="Evictor"
     className="com.ibm.websphere.objectgrid.plugins.builtins.LFUEvictor/>
   <bean id="OptimisticCallback"
     className="com.ibm.websphere.samples.objectgrid.EmployeeOptimisticCallBackImpl"/>
  </backingMapPluginCollection>
  </backingMapPluginCollections>
</objectGridConfig>

The following code sample demonstrates the programmatic approach to achieving the same configuration as the companyGridCollection.xml file in the preceding example.

ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();

ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);
BackingMap customerMap = companyGrid .defineMap("Customer");
LRUEvictor customerEvictor = new LRUEvictor();
customerMap.setEvictor(customerEvictor);

BackingMap itemMap = companyGrid.defineMap("Item");
LFUEvictor itemEvictor = new LFUEvictor();
itemMap.setEvictor(itemEvictor);

BackingMap orderLineMap = companyGrid.defineMap("OrderLine");
LFUEvictor orderLineEvictor = new LFUEvictor();
orderLineMap.setEvictor(orderLineEvictor);

BackingMap orderMap = companyGrid.defineMap("Order");

querySchema element

The querySchema element defines relationships between BackingMaps and identifies the type of object in each map. This information is used by ObjectQuery to translate query language strings into map access calls. For more information, see Configuring an ObjectQuery schema .

• Number of occurrences: Zero to one
• Child element: mapSchemas element, relationships element

mapSchemas element

Each querySchema element has one mapSchemas element that contains one or more mapSchema elements.

• Number of occurrences: One
• Child element: mapSchema element

mapSchema element

A mapSchema element defines the type of object that is stored in a BackingMap and instructions on how to access the data.

• Number of occurrences: One or more
• Child element: None

Attributes

mapName

Name of the BackingMap to add to the schema. (Required)

valueClass

Type of object that is stored in the value portion of the BackingMap. (Required)

primaryKeyField

Name of the primary key attribute in the valueClass attribute. The primary key must also be stored in the key portion of the BackingMap. (Optional)

accessType

Identifies how the query engine introspects and accesses the persistent data in the valueClass object instances. If you set the value to FIELD, the class fields are introspected and added to the schema. If the value is

PROPERTY, the attributes that are associated with get and is methods are used. The default value is

PROPERTY. (Optional)

<mapSchema (1)   mapName="backingMapName"
(2)   valueClass="com.mycompany.OrderBean"
(3)   primaryKeyField="orderId"
(4)   accessType="PROPERTY" | "FIELD"
/>

In the following example, the companyGridQuerySchemaAttr.xml file is used to demonstrate a sample mapSchema configuration.

<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
 xmlns="http://ibm.com/ws/objectgrid/config">

 <objectGrids>
  <objectGrid name="CompanyGrid">
   <backingMap name="Order"/>
   <backingMap name="Customer"/>

   <querySchema>
    <mapSchemas>
     <mapSchema mapName="Order"
      valueClass="com.mycompany.OrderBean"
      primaryKeyField="orderNumber"
      accessType="FIELD"/>
     <mapSchema mapName="Customer"
      valueClass="com.mycompany.CustomerBean"
      primaryKeyField="id"
      accessType="FIELD"/>
    </mapSchemas>
   </querySchema>
  </objectGrid>
 </objectGrids>
</objectGridConfig>

The following code sample demonstrates the programmatic approach to achieving the same configuration as the companyGridQuerySchemaAttr.xml file in the preceding example.

ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);
companyGrid.defineMap("Order");
companyGrid.defineMap("Customer");

// Define the schema QueryConfig queryCfg = new QueryConfig();
queryCfg.addQueryMapping(new QueryMapping(
    "Order", OrderBean.class.getName(), "orderNumber", QueryMapping.FIELD_ACCESS));
queryCfg.addQueryMapping(new QueryMapping(
    "Customer", CustomerBean.class.getName(), "id", QueryMapping.FIELD_ACCESS));
companyGrid.setQueryConfig(queryCfg);

relationships element

Each querySchema element has zero or one relationships element that contains one or more relationship elements.

• Number of occurrences: Zero or one
• Child element: relationship element

relationship element

A relationship element defines the relationship between two BackingMaps and the attributes in the valueClass attribute that bind the relationship.

• Number of occurrences: One or more
• Child element: None

Attributes

source

Name of the valueClass of the source side of a relationship. (Required)

target

Name of the valueClass of the target side of a relationship. (Required)

relationField

Name of the attribute in the source valueClass that refers to the target. (Required)

invRelationField

Name of the attribute in the target valueClass that refers to the source. If this attribute is not specified, the relationship is one directional. (Optional)

<mapSchema (1)   source="com.mycompany.OrderBean"
(2)   target="com.mycompany.CustomerBean"
(3)   relationField="customer"
(4)   invRelationField="orders"
/>

In the following example, the companyGridQuerySchemaWithRelationshipAttr.xml file is used to demonstrate a sample mapSchema configuration that includes a bidirectional relationship.

<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
 xmlns="http://ibm.com/ws/objectgrid/config">

 <objectGrids>
  <objectGrid name="CompanyGrid">
   <backingMap name="Order"/>
   <backingMap name="Customer"/>

   <querySchema>
    <mapSchemas>
     <mapSchema mapName="Order"
      valueClass="com.mycompany.OrderBean"
      primaryKeyField="orderNumber"
      accessType="FIELD"/>
     <mapSchema mapName="Customer"
      valueClass="com.mycompany.CustomerBean"
      primaryKeyField="id"
      accessType="FIELD"/>
    </mapSchemas>
    <relationships>
     <relationship source="com.mycompany.OrderBean"
      target="com.mycompany.CustomerBean"
      relationField="customer"/>
      invRelationField="orders"/>
    </relationships>
   </querySchema>
  </objectGrid>
 </objectGrids>
</objectGridConfig>

The following code sample demonstrates the programmatic approach to achieving the same configuration as the companyGridQuerySchemaWithRelationshipAttr.xml file in the preceding example.

ObjectGridManager objectGridManager = ObjectGridManagerFactory.getObjectGridManager();
ObjectGrid companyGrid = objectGridManager.createObjectGrid("CompanyGrid", false);
companyGrid.defineMap("Order");
companyGrid.defineMap("Customer");

// Define the schema QueryConfig queryCfg = new QueryConfig();
queryCfg.addQueryMapping(new QueryMapping(
    "Order", OrderBean.class.getName(), "orderNumber", QueryMapping.FIELD_ACCESS));
queryCfg.addQueryMapping(new QueryMapping(
    "Customer", CustomerBean.class.getName(), "id", QueryMapping.FIELD_ACCESS));
queryCfg.addQueryRelationship(new QueryRelationship(
     OrderBean.class.getName(), CustomerBean.class.getName(), "customer", "orders"));
companyGrid.setQueryConfig(queryCfg);

stream element

The stream element represents a stream to the stream query engine. Each attribute of the stream element corresponds to a method on the StreamMetadata interface.

• Number of occurrences: One to many
• Child element: basic element

Attributes

name

Name of the stream. Validation fails if this attribute is not specified. (Required)

valueClass

Class type of the value that is stored in the stream ObjectMap. The class type is used to convert the object to the stream events and to generate an SQL statement if the statement is not provided. (Required)

sql

SQL statement of the stream. If this property is not provided, a stream SQL is generated by reflecting the attributes or accessor methods on the valueClass attribute or using the tuple attributes of the entity metadata. (Optional)

access

Type to access the attributes of the value class. If you set the value to FIELD, the attributes are directly retrieved from the fields using Java reflection. Otherwise, accessor methods are used to read the attributes. The default value is

PROPERTY. (Optional)

<stream (1) name="streamName"
(2) valueClass="streamMapClassType"
(3) sql="streamSQL create stream stockQuote keyed by t ( transactionvolume INTEGER, price DECIMAL (9,2), issue VARCHAR(100) );"
(4) access="PROPERTY" | "FIELD"
/>

view element

The view element represents a stream query view. Each stream element corresponds to a method on the ViewMetadata interface.

• Number of occurrences: One to many
• Child element: basic element, ID element

Attributes

name

Name of the view. Validation fails if this attribute is not specified. (Required)

sql

SQL of the stream, which defines the view transformation. Validation fails if this attribute is not specified. (Required)

valueClass

Class type of the value that is stored in this view of the ObjectMap. The class type is used to convert view events into the correct tuple format that is compatible with this class type. If the class type is not provided, a default format following the column definitions in the Stream Processing Technology Structured Query Language (SPTSQL) is used. If an entity metadata is defined for this view map, do not use the valueClass attribute. (Optional)

access

Type to access the attributes of the value class. If you set the access type to FIELD, the column values are directly set to the fields using Java reflection. Otherwise, accessor methods are used to set the attributes. The default value is

PROPERTY. (Optional)

<view (1)   name="viewName"
(2)   valueClass="viewMapValueClass"
(3)   sql="viewSQL CREATE VIEW last5MinuteAvgPrice AS
      SELECT issue, avg(price) as totalVolume FROM (SELECT * FROM stockQuote FETCH LATEST 5 MINUTES) group by issue;"/>
(4)   access="PROPERTY" | "FIELD"
/>

basic element

The basic element is used to define a mapping from the attribute name in the value class or entity metadata to the column that is defined in the SPTSQL.

• Number of occurrences: Zero to many
• Child element: None

<basic (1)   name="attributeName"
(2)   column="columnName"
/>

id element

The id element is used for a key attribute mapping.

• Number of occurrences: Zero to many
• Child element: None

<id (1)   name="idName"
(2)   column="columnName"
/>

objectGrid.xsd file

Use the ObjectGrid descriptor XML schema to configure WebSphere eXtreme Scale.

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:cc="http://ibm.com/ws/objectgrid/config" xmlns:dgc="http://ibm.com/ws/objectgrid/config" elementFormfalse ="qualified" targetNamespace="http://ibm.com/ws/objectgrid/config">

 <xsd:element name="objectGridConfig">
  <xsd:complexType>
   <xsd:sequence>
                <xsd:element maxOccurs="1" minOccurs="1" name="objectGrids" type="dgc:objectGrids">
     <xsd:unique name="objectGridNameUnique">
      <xsd:selector xpath="dgc:objectGrid" />
      <xsd:field xpath="@name" />
     </xsd:unique>
    </xsd:element>
    <xsd:element maxOccurs="1" minOccurs="0" name="backingMapPluginCollections" type="dgc:backingMapPluginCollections" />
   </xsd:sequence>
  </xsd:complexType>

  <xsd:key name="backingMapPluginCollectionId">
   <xsd:selector xpath="dgc:backingMapPluginCollections/dgc:backingMapPluginCollection" />
   <xsd:field xpath="@id" />
  </xsd:key>

  <xsd:keyref name="pluginCollectionRef" refer="dgc:backingMapPluginCollectionId">
   <xsd:selector xpath="dgc:objectGrids/dgc:objectGrid/dgc:backingMap" />
   <xsd:field xpath="@pluginCollectionRef" />
  </xsd:keyref>
 </xsd:element>

 <xsd:complexType name="objectGrids">
  <xsd:sequence>
   <xsd:element maxOccurs="unbounded" minOccurs="1" name="objectGrid" type="dgc:objectGrid">
    <xsd:unique name="backingMapNameUnique">
     <xsd:selector xpath="dgc:backingMap" />
     <xsd:field xpath="@name" />
    </xsd:unique>
   </xsd:element>
  </xsd:sequence>
 </xsd:complexType>

 <xsd:complexType name="backingMapPluginCollections">
  <xsd:sequence>
   <xsd:element maxOccurs="unbounded" minOccurs="0" name="backingMapPluginCollection" type="dgc:backingMapPluginCollection" />
  </xsd:sequence>
 </xsd:complexType>

 <xsd:complexType name="objectGrid">
  <xsd:sequence>
   <xsd:element maxOccurs="unbounded" minOccurs="0" name="bean" type="dgc:gridBean"/>
   <xsd:element maxOccurs="unbounded" minOccurs="0" name="backingMap" type="dgc:backingMap" />
   <xsd:element maxOccurs="1" minOccurs="0" name="querySchema" type="dgc:querySchema"/>
  </xsd:sequence>
  <xsd:attribute name="name" type="xsd:string" use="required" />
  <xsd:attribute name="authorizationMechanism" type="dgc:authorizationMechanism" use="optional" />
  <xsd:attribute name="accessByCreatorOnlyMode" type="dgc:accessByCreatorOnlyMode" use="optional" />
  <xsd:attribute name="securityEnabled" type="xsd:boolean" use="optional" />
  <xsd:attribute name="txTimeout" type="xsd:int" use="optional" />
  <xsd:attribute name="permissionCheckPeriod" type="xsd:int" use="optional" />
  <xsd:attribute name="entityMetadataXMLFile" type="xsd:string" use="optional" />
  <xsd:attribute name="initialState" type="dgc:initialState" use="optional" />
  <xsd:attribute name="txIsolation" type="dgc:transactionIsolation" use="optional" />
 </xsd:complexType>


 <xsd:complexType name="backingMap">
  <xsd:sequence>
   <xsd:element maxOccurs="1" minOccurs="0" name="timeBasedDBUpdate" type="dgc:timeBasedDBUpdate" />
  </xsd:sequence>
  <xsd:attribute name="name" type="xsd:string" use="required" />
  <xsd:attribute name="readOnly" type="xsd:boolean" use="optional" />
        <xsd:attribute name="pluginCollectionRef" type="xsd:string" use="optional"/>
        <xsd:attribute name="preloadMode" type="xsd:boolean" use="optional"/>
        <xsd:attribute name="lockStrategy" type="dgc:lockStrategy" use="optional"/>
  <xsd:attribute name="copyMode" type="dgc:copyMode" use="optional" />
        <xsd:attribute name="valueInterfaceClassName" type="xsd:string" use="optional"/>
        <xsd:attribute name="numberOfBuckets" type="xsd:int" use="optional"/>
        <xsd:attribute name="nullValuesSupported" type="xsd:boolean" use="optional"/>
  <xsd:attribute name="lockTimeout" type="xsd:int" use="optional" />
        <xsd:attribute name="numberOfLockBuckets" type="xsd:int" use="optional"/>
  <xsd:attribute name="copyKey" type="xsd:boolean" use="optional" />
  <xsd:attribute name="timeToLive" type="xsd:int" use="optional" />
        <xsd:attribute name="ttlEvictorType" type="dgc:ttlEvictorType" use="optional"/>
  <xsd:attribute name="writeBehind" type="xsd:string" use="optional" />
        <xsd:attribute name="evictionTriggers" type="xsd:string" use="optional"/>
  <xsd:attribute name="template" type="xsd:boolean" use="optional" />
        <xsd:attribute name="nearCacheInvalidationEnabled" type="xsd:boolean" use="optional"/>
        <xsd:attribute name="nearCacheLastAccessTTLSyncEnabled" type="xsd:boolean" use="optional"/>
        <xsd:attribute name="nearCacheEnabled" type="xsd:boolean" use="optional"/>
        <xsd:attribute name="keyOutputFormat" type="dgc:outputFormat" use="optional"/>
        <xsd:attribute name="valueOutputFormat" type="dgc:outputFormat" use="optional"/>
 </xsd:complexType>



 <xsd:complexType name="gridBean">
  <xsd:sequence>
            <xsd:element maxOccurs="unbounded" minOccurs="0" name="property" type="dgc:property"/>
  </xsd:sequence>
  <xsd:attribute name="className" type="xsd:string" use="optional" />
  <xsd:attribute name="id" type="dgc:gridBeanId" use="required" />
  <xsd:attribute name="osgiService" type="xsd:string" use="optional" />
 </xsd:complexType>
 
    <xsd:complexType name="mapBean">
        <xsd:sequence>
            <xsd:element maxOccurs="unbounded" minOccurs="0" name="property"
                type="dgc:property" />
        </xsd:sequence>
        <xsd:attribute name="className" type="xsd:string" use="optional" />
        <xsd:attribute name="id" type="dgc:mapBeanId" use="required" />
        <xsd:attribute name="osgiService" type="xsd:string" use="optional" />
    </xsd:complexType>
 

 <xsd:complexType name="backingMapPluginCollection">
  <xsd:sequence>
   <xsd:element maxOccurs="unbounded" minOccurs="0" name="bean" type="dgc:mapBean"/>
  </xsd:sequence>
  <xsd:attribute name="id" type="xsd:string" use="required" />
 </xsd:complexType>

 <xsd:complexType name="property">
  <xsd:attribute name="name" type="xsd:string" use="required" />
  <xsd:attribute name="value" type="xsd:string" use="required" />
  <xsd:attribute name="type" type="dgc:propertyType" use="required" />
  <xsd:attribute name="description" type="xsd:string" use="optional" />
 </xsd:complexType>

 <xsd:simpleType name="propertyType">
  <xsd:restriction base="xsd:string">
   <xsd:enumeration value="java.lang.Boolean" />
   <xsd:enumeration value="boolean" />
   <xsd:enumeration value="java.lang.String" />
   <xsd:enumeration value="java.lang.Integer" />
   <xsd:enumeration value="int" />
   <xsd:enumeration value="java.lang.Double" />
   <xsd:enumeration value="double" />
   <xsd:enumeration value="java.lang.Byte" />
   <xsd:enumeration value="byte" />
   <xsd:enumeration value="java.lang.Short" />
   <xsd:enumeration value="short" />
   <xsd:enumeration value="java.lang.Long" />
   <xsd:enumeration value="long" />
   <xsd:enumeration value="java.lang.Float" />
   <xsd:enumeration value="float" />
   <xsd:enumeration value="java.lang.Character" />
   <xsd:enumeration value="char" />
  </xsd:restriction>
 </xsd:simpleType>

 <xsd:simpleType name="gridBeanId">
  <xsd:restriction base="xsd:string">
   <xsd:enumeration value="TransactionCallback" />
   <xsd:enumeration value="ObjectGridEventListener" />
   <xsd:enumeration value="ObjectGridLifecycleListener" />
   <xsd:enumeration value="SubjectSource" />
   <xsd:enumeration value="SubjectValidation" />
   <xsd:enumeration value="ObjectGridAuthorization" />
   <xsd:enumeration value="CollisionArbiter" />
  </xsd:restriction>
 </xsd:simpleType>


 <xsd:simpleType name="mapBeanId">         
  <xsd:restriction base="xsd:string">
   <xsd:enumeration value="Loader" />
   <xsd:enumeration value="ObjectTransformer" />
   <xsd:enumeration value="OptimisticCallback" />
   <xsd:enumeration value="Evictor" />
   <xsd:enumeration value="MapEventListener" />
   <xsd:enumeration value="BackingMapLifecycleListener" />
   <xsd:enumeration value="MapIndexPlugin" />
   <xsd:enumeration value="MapSerializerPlugin" />
  </xsd:restriction>
 </xsd:simpleType>

 <xsd:simpleType name="copyMode">
  <xsd:restriction base="xsd:string">
   <xsd:enumeration value="COPY_ON_READ_AND_COMMIT" />
   <xsd:enumeration value="COPY_ON_READ" />
   <xsd:enumeration value="COPY_ON_WRITE" />
   <xsd:enumeration value="NO_COPY" />
   <xsd:enumeration value="COPY_TO_BYTES" />
   <xsd:enumeration value="COPY_TO_BYTES_RAW" />
  </xsd:restriction>
 </xsd:simpleType>

 <xsd:simpleType name="lockStrategy">
  <xsd:restriction base="xsd:string">
   <xsd:enumeration value="OPTIMISTIC" />
   <xsd:enumeration value="PESSIMISTIC" />
   <xsd:enumeration value="NONE" />
  </xsd:restriction>
 </xsd:simpleType>

 <xsd:simpleType name="ttlEvictorType">
  <xsd:restriction base="xsd:string">
   <xsd:enumeration value="CREATION_TIME" />
   <xsd:enumeration value="LAST_ACCESS_TIME" />
   <xsd:enumeration value="LAST_UPDATE_TIME" />
   <xsd:enumeration value="NONE" />
  </xsd:restriction>
 </xsd:simpleType>

 <xsd:simpleType name="authorizationMechanism">
  <xsd:restriction base="xsd:string">
   <xsd:enumeration value="AUTHORIZATION_MECHANISM_JAAS" />
   <xsd:enumeration value="AUTHORIZATION_MECHANISM_CUSTOM" />
  </xsd:restriction>
 </xsd:simpleType>

 <xsd:simpleType name="accessByCreatorOnlyMode">
  <xsd:restriction base="xsd:string">
   <xsd:enumeration value="disabled" />
   <xsd:enumeration value="complement" />
   <xsd:enumeration value="supersede" />
  </xsd:restriction>
 </xsd:simpleType>

 <!-- The following is added by Jian for time-based database update -->
 <xsd:complexType name="timeBasedDBUpdate">
        <xsd:attribute name="persistenceUnitName" type="xsd:string" use="optional"/>
  <xsd:attribute name="mode" type="cc:dbUpdateMode" use="optional" />
        <xsd:attribute name="timestampField" type="xsd:string" use="optional"/>
  <xsd:attribute name="entityClass" type="xsd:string" use="required" />
        <xsd:attribute name="jpaPropertyFactory" type="xsd:string" use="optional"/>
 </xsd:complexType>

 <xsd:simpleType name="dbUpdateMode">
  <xsd:restriction base="xsd:string">
   <xsd:enumeration value="INVALIDATE_ONLY" />
   <xsd:enumeration value="UPDATE_ONLY" />
   <xsd:enumeration value="INSERT_UPDATE" />
  </xsd:restriction>
 </xsd:simpleType>



 <!-- The following is added by Jian for single query -->
 <xsd:complexType name="querySchema">
  <xsd:sequence>
            <xsd:element maxOccurs="1" minOccurs="1" name="mapSchemas" type="dgc:mapSchemas">
    <xsd:unique name="mapNameUnique">
     <xsd:selector xpath="dgc:mapSchema" />
     <xsd:field xpath="@mapName" />
    </xsd:unique>
   </xsd:element>
            <xsd:element maxOccurs="1" minOccurs="0" name="relationships" type="dgc:relationships"/>
  </xsd:sequence>
 </xsd:complexType>

 <xsd:complexType name="mapSchemas">
  <xsd:sequence>
            <xsd:element maxOccurs="unbounded" minOccurs="1" name="mapSchema" type="dgc:mapSchema"/>
  </xsd:sequence>
 </xsd:complexType>

 <xsd:complexType name="relationships">
  <xsd:sequence>
            <xsd:element maxOccurs="unbounded" minOccurs="1" name="relationship" type="dgc:relationship"/>
  </xsd:sequence>
 </xsd:complexType>

 <xsd:complexType name="mapSchema">
  <xsd:attribute name="mapName" type="xsd:string" use="required" />
  <xsd:attribute name="valueClass" type="xsd:string" use="required" />
        <xsd:attribute name="primaryKeyField" type="xsd:string" use="optional"/>
        <xsd:attribute name="accessType" type="cc:accessType" use="optional"/>
 </xsd:complexType>

 <xsd:complexType name="relationship">
  <xsd:attribute name="source" type="xsd:string" use="required" />
  <xsd:attribute name="target" type="xsd:string" use="required" />
        <xsd:attribute name="relationField" type="xsd:string" use="required"/>
        <xsd:attribute name="invRelationField" type="xsd:string" use="optional"/>
 </xsd:complexType>

 <xsd:simpleType name="accessType">
  <xsd:restriction base="xsd:string">
   <xsd:enumeration value="PROPERTY" />
   <xsd:enumeration value="FIELD" />
  </xsd:restriction>
 </xsd:simpleType>

 <xsd:simpleType name="initialState">
  <xsd:restriction base="xsd:string">
   <xsd:enumeration value="OFFLINE" />
   <xsd:enumeration value="PRELOAD" />
   <xsd:enumeration value="ONLINE" />
  </xsd:restriction>
 </xsd:simpleType>

 <xsd:simpleType name="transactionIsolation">
  <xsd:restriction base="xsd:string">
   <xsd:enumeration value="READ_UNCOMMITTED" />
   <xsd:enumeration value="READ_COMMITTED" />
   <xsd:enumeration value="REPEATABLE_READ" />
  </xsd:restriction>
 </xsd:simpleType>

 <xsd:simpleType name="outputFormat">
        <xsd:restriction base="xsd:string">
            <xsd:enumeration value="NATIVE"/>
            <xsd:enumeration value="RAW"/>
        </xsd:restriction>
    </xsd:simpleType>
</xsd:schema>

Deployment policy descriptor XML file

To configure a deployment policy, use a deployment policy descriptor XML file.

In the following sections, the elements and attributes of the deployment policy descriptor XML file are defined.

Elements in the deploymentPolicy.xml file

(1) <deploymentPolicy>
(2)  <objectgridDeployment objectGridName="blah">
(3)   <mapSet (4)    name="mapSetName"
(5)    numberOfPartitions="numberOfPartitions"
(6)    minSyncReplicas="minimumNumber"
(7)     maxSyncReplicas="maximumNumber"
(8)    maxAsyncReplicas="maximumNumber"
(9)    replicaReadEnabled="true|false"
(10)    numInitialContainers="numberOfInitialContainersBeforePlacement"
(11)    autoReplaceLostShards="true|false"
(12)    developmentMode="true|false"
(13)    placementStrategy="FIXED_PARTITION|PER_CONTAINER">
(14)    <map ref="backingMapReference" />
(15)
(16)     <zoneMetadata>
(17)      <shardMapping (18)        shard="shardType"
(19)        zoneRuleRef="zoneRuleRefName" />
(20)      <zoneRule 
(21)        name="zoneRuleName"
(22)        exclusivePlacement="true|false" >
(23)        <zone name="ALPHA" />
(24)        <zone name="BETA" />
(25)        <zone name="GAMMA" />
(26)      </zoneRule>
(27)     </zoneMetadata>
(28)    </mapSet>
(29)  </objectgridDeployment>
(30) </deploymentPolicy>

deploymentPolicy element (line 1)

The deploymentPolicy element is the top-level element of the deployment policy XML file. This element sets up the namespace of the file and the schema location. The schema is defined in the deploymentPolicy.xsd file.

• Number of occurrences: One
• Child element: objectgridDeployment

objectgridDeployment element (line 2)

The objectgridDeployment element is used to reference an ObjectGrid instance from the ObjectGrid XML file. Within the objectgridDeployment element, we can divide your maps into map sets .

• Number of occurrences: One or more
• Child element: mapSet

Attributes

objectgridName

Name of the ObjectGrid instance to deploy. This attribute references an objectGrid element that is defined in the ObjectGrid XML file. (Required)

For example, the objectgridName attribute is set as

CompanyGrid in the companyGridDpReplication.xml file. The objectgridName attribute references the CompanyGrid that is defined in the companyGrid.xml file. Read about the ObjectGrid descriptor XML file which you should couple with the deployment policy file for each ObjectGrid instance.

mapSet element (line 3)

The mapSet element is used to group maps together. The maps within a mapSet element are partitioned and replicated similarly. Each map must belong to only one mapSet element.

• Number of occurrences: One or more
• Child elements:
  • map
  • zoneMetadata

Attributes

name

Name of the mapSet. This attribute must be unique within the objectgridDeployment element. (Required)

numberOfPartitions

Number of partitions for the mapSet element. The default value is 1. The number should be appropriate for the number of container servers that host the partitions. (Optional)

minSyncReplicas

Minimum number of synchronous replicas for each partition in the mapSet. The default value is 0. Shards are not placed until the domain can support the minimum number of synchronous replicas. To support the minSyncReplicas value, you need one more container server than the minSyncReplicas value. If the number of synchronous replicas falls below the minSyncReplicas value, write transactions are no longer allowed for that partition. (Optional)

maxSyncReplicas

Maximum number of synchronous replicas for each partition in the mapSet. The default value is 0. No other synchronous replicas are placed for a partition after a domain reaches this number of synchronous replicas for that specific partition. Adding container servers that can support this ObjectGrid can result in an increased number of synchronous replicas if your maxSyncReplicas value has not already been met. (Optional)

maxAsyncReplicas

Maximum number of asynchronous replicas for each partition in the mapSet. The default value is 0. After the primary and all synchronous replicas have been placed for a partition, asynchronous replicas are placed until the maxAsyncReplicas value is met. (Optional)

replicaReadEnabled

If set true, read requests are distributed amongst a partition primary and its replicas. If the replicaReadEnabled attribute is false, read requests are routed to the primary only. The default value is false. (Optional)

numInitialContainers

Number of container servers that are required before initial placement occurs for the shards in this mapSet element. The default value is

1. This attribute can help save process and network bandwidth when bringing a data grid online from a cold startup. (Optional)

We can also use the placementDeferralInterval property and the xscmd -c suspendBalancing command to delay the initial placement of shards on the container servers.

Starting a container server sends an event to the catalog service. The first time that the number of active container servers is equal to the numInitialContainers value for a mapSet element, the catalog service places the shards from the mapSet, provided that the minSyncReplicas value can also be satisfied. After the numInitialContainers value has been met, each container server-started event can trigger a rebalance of unplaced and previously placed shards. If you know approximately how many container servers we are going to start for this mapSet element, we can set the numInitialContainers value close to that number to avoid the rebalance after every container server start. Placement occurs only when you reach the numInitialContainers value specified in the mapSet element.

If you ever need to override the numInitialContainers value, for example, when we are performing maintenance on your servers and want shard placement to continue running, we can use the xscmd -c triggerPlacement command. This override is temporary and is applied when we run the command. After we run the command, all subsequent placement runs use the numInitialContainers value.

autoReplaceLostShards

Specifies if lost shards are placed on other container servers. The default value is true. When a container server is stopped or fails, the shards running on the container server are lost. A lost primary shard causes one of its replica shards to be promoted to the primary shard for the corresponding partition. Because of this promotion, one of the replicas is lost. If we want lost shards to remain unplaced, set the autoReplaceLostShards attribute to false. This setting does not affect the promotion chain, but only the replacement of the last shard in the chain. (Optional)

developmentMode

With this attribute, we can influence where a shard is placed in relation to its peer shards. The default value is true. When the developmentMode attribute is set to false, no two shards from the same partition are placed on the same computer. When the developmentMode attribute is set to true, shards from the same partition can be placed on the same machine. In either case, no two shards from the same partition are ever placed in the same container server. (Optional)

placementStrategy

There are two placement strategies. The default strategy is

FIXED_PARTITION, where the number of primary shards placed across available container servers is equal to the number of partitions defined, increased by the number of replicas. The alternate strategy is

PER_CONTAINER, where the number of primary shards placed on each container server is equal to the number of partitions that are defined, with an equal number of replicas placed on other container servers. (Optional)

map element (line 14)

Each map in a mapSet element references one of the backingMap elements that is defined in the corresponding ObjectGrid XML file. Every map in a distributed eXtreme Scale environment can belong to only one mapSet element.

• Number of occurrences: One or more
• Child element: None

Attributes

ref

Provides a reference to a backingMap element in the ObjectGrid XML file. Each map in a mapSet element must reference a backingMap element from the ObjectGrid XML file. The value that is assigned to the ref attribute must match the name attribute of one of the backingMap elements in the ObjectGrid XML file, as in the following code snippet. (Required)

zoneMetadata element (line 16)

We can place shards into zones. This function allows more control over how eXtreme Scale places shards on a grid. Java virtual machines that host a WXS server can be tagged with a zone identifier. The deployment file can include one or more zone rules, and these zone rules are associated with a shard type. The zoneMetadata element is a receptacle of zone configuration elements. Within the zoneMetadata element, zones can be defined and shard placement behavior can be influenced.

For additional background, see Configuring zones for replica placement .

• Number of occurrences: Zero or one
• Child elements:
  • shardMapping
  • zoneRule

Attributes: None

shardMapping element (line 17)

The shardMapping element is used to associate a shard type with a zone rule. Placement of the shard is influenced by the mapping to the zone rule.

• Number of occurrences: Zero or one
• Child elements: None

Attributes

shard

Specify the name of a shard with which to associate the zoneRule. (Required)

zoneRuleRef

Specify the name of a zoneRule with which to associate the shard. (Optional)

zoneRule element (line 20)

A zone rule specifies the possible set of zones in which a shard can be placed. The zoneRule element is used to specify a set of zones that a set of shard types can be placed within. The zone rule can also be used to determine how shards are grouped across the zones using the exclusivePlacement attribute.

• Number of occurrences: One or more
• Child elements: zone

Attributes

name

Specify the name of the zone rule that you defined previously, as the zoneRuleRef in a shardMapping element. (Required)

exclusivePlacement

An exclusive setting indicates that each shard type mapped to this zone rule is placed in a different zone in the zone list. An inclusive setting indicates that after a shard is placed in a zone from the list, then the other shard types mapped to this zone rule are also placed in that zone. Note that using an exclusive setting with three shards mapped to the same zone rule (primary, and two synchronous replicas) would require at least 3 zones in order for all shards to be placed. (Optional)

zone element (lines 23 to 25)

The zone element is used to name a zone within a zone rule. Each zone named should correspond to a zone name used to launch servers.

In the following example, the mapSet element is used to configure a deployment policy. The value is set to mapSet1, and is divided into 10 partitions. Each of these partitions must have at least one synchronous replica available and no more than two synchronous replicas. Each partition also has an asynchronous replica if the environment can support it. All synchronous replicas are placed before any asynchronous replicas are placed. Additionally, the catalog service does not attempt to place the shards for the mapSet1 element until the domain can support the minSyncReplicas value. Supporting the minSyncReplicas value requires two or more container servers: one for the primary and two for the synchronous replica.

<?xml version="1.0" encoding="UTF-8"?>
<deploymentPolicy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://ibm.com/ws/objectgrid/deploymentPolicy ../deploymentPolicy.xsd"
 xmlns="http://ibm.com/ws/objectgrid/deploymentPolicy">

 <objectgridDeployment objectgridName="CompanyGrid">
  <mapSet name="mapSet1" numberOfPartitions="10"
   minSyncReplicas="1" maxSyncReplicas="2" maxAsyncReplicas="1"
    numInitialContainers="10" autoReplaceLostShards="true"
   developmentMode="false" replicaReadEnabled="true">
   <map ref="Customer"/>
   <map ref="Item"/>
   <map ref="OrderLine"/>
   <map ref="Order"/>
  </mapSet>
 </objectgridDeployment>

</deploymentPolicy>

Although only two container servers are required to satisfy the replication settings, the numInitialContainers attribute requires 10 available container servers before the catalog service attempts to place any of the shards in this mapSet element. After the domain has 10 container servers that are able to support the CompanyGrid ObjectGrid, all shards in the mapSet1 element are placed.

Because the autoReplaceLostShards attribute is set to true, any shard in this mapSet element that is lost as the result of container server failure is automatically replaced onto another container server, provided that a container server is available to host the lost shard. Shards from the same partition cannot be placed on the same machine for the mapSet1 element because the developmentMode attribute is set to false. Read-only requests are distributed across the primary shardand its replicas for each partition because the replicaReadEnabled value is true.

The companyGridDpMapSetAttr.xml file uses the ref attribute on the map to reference each of the backingMap elements from the companyGrid.xml file.

deploymentPolicy.xsd file

Use the deployment policy XML schema to create a deployment descriptor XML file.

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:dp="http://ibm.com/ws/objectgrid/deploymentPolicy"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://ibm.com/ws/objectgrid/deploymentPolicy"
    elementFormfalse ="qualified">

    <xsd:element name="deploymentPolicy">
        <xsd:complexType>
            <xsd:choice>
                <xsd:element name="objectgridDeployment"
                    type="dp:objectgridDeployment" minOccurs="1"
                    maxOccurs="unbounded">
                    <xsd:unique name="mapSetNameUnique">
                        <xsd:selector xpath="dp:mapSet" />
                        <xsd:field xpath="@name" />
                    </xsd:unique>
                </xsd:element>
            </xsd:choice>
        </xsd:complexType>
    </xsd:element>

    <xsd:complexType name="objectgridDeployment">
        <xsd:sequence>
            <xsd:element name="mapSet" type="dp:mapSet"
                maxOccurs="unbounded" minOccurs="1">
                <xsd:unique name="mapNameUnique">
                    <xsd:selector xpath="dp:map" />
                    <xsd:field xpath="@ref" />
                </xsd:unique>
            </xsd:element>
        </xsd:sequence>
        <xsd:attribute name="objectgridName" type="xsd:string"
            use="required" />
    </xsd:complexType>


    <xsd:complexType name="mapSet">
        <xsd:sequence>
            <xsd:element name="map" type="dp:map" maxOccurs="unbounded"
                minOccurs="1" />
            <xsd:element name="zoneMetadata" type="dp:zoneMetadata"
                maxOccurs="1" minOccurs="0">

                <xsd:key name="zoneRuleName">
                    <xsd:selector xpath="dp:zoneRule" />
                    <xsd:field xpath="@name" />
                </xsd:key>

                <xsd:keyref name="zoneRuleRef"
                    refer="dp:zoneRuleName">
                    <xsd:selector xpath="dp:shardMapping" />
                    <xsd:field xpath="@zoneRuleRef" />
                </xsd:keyref>

            </xsd:element>
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="numberOfPartitions" type="xsd:int"
            use="optional" />
        <xsd:attribute name="minSyncReplicas" type="xsd:int"
            use="optional" />
        <xsd:attribute name="maxSyncReplicas" type="xsd:int"
            use="optional" />
        <xsd:attribute name="maxAsyncReplicas" type="xsd:int"
            use="optional" />
        <xsd:attribute name="replicaReadEnabled" type="xsd:boolean"
            use="optional" />
        <xsd:attribute name="numInitialContainers" type="xsd:int"
            use="optional" />
        <xsd:attribute name="autoReplaceLostShards" type="xsd:boolean"
            use="optional" />
        <xsd:attribute name="developmentMode" type="xsd:boolean"
            use="optional" />
        <xsd:attribute name="placementStrategy"
            type="dp:placementStrategy" use="optional" />
        <xsd:attribute name="placementScope"
            type="dp:placementScope" default="DOMAIN_SCOPE" use="optional" />
        <xsd:attribute name="placementScopeTopology"
            type="dp:placementScopeTopology" default="RING" use="optional" />
    </xsd:complexType>

    <xsd:simpleType name="placementStrategy">
        <xsd:restriction base="xsd:string">
            <xsd:enumeration value="FIXED_PARTITIONS" />
            <xsd:enumeration value="PER_CONTAINER" />
        </xsd:restriction>
    </xsd:simpleType>

    <xsd:simpleType name="placementScope">
        <xsd:restriction base="xsd:string">
            <xsd:enumeration value="DOMAIN_SCOPE" />
            <xsd:enumeration value="CONTAINER_SCOPE" />
<!--            <xsd:enumeration value="ZONE_SCOPE" /> -->
        </xsd:restriction>
    </xsd:simpleType>

    <xsd:simpleType name="placementScopeTopology">
        <xsd:restriction base="xsd:string">
            <xsd:enumeration value="RING" />
            <xsd:enumeration value="HUB" /> 
        </xsd:restriction>
    </xsd:simpleType>


    <xsd:complexType name="map">
        <xsd:attribute name="ref" use="required" />
    </xsd:complexType>

    <xsd:complexType name="zoneMetadata">
        <xsd:sequence>
            <xsd:element name="shardMapping" type="dp:shardMapping"
                maxOccurs="unbounded" minOccurs="1" />
            <xsd:element name="zoneRule" type="dp:zoneRule"
                maxOccurs="unbounded" minOccurs="1">

            </xsd:element>

        </xsd:sequence>
    </xsd:complexType>

    <xsd:complexType name="shardMapping">
        <xsd:attribute name="shard" use="required">
         <xsd:simpleType>
          <xsd:restriction base="xsd:string">
           <xsd:enumeration value="P"></xsd:enumeration>
           <xsd:enumeration value="S"></xsd:enumeration>
           <xsd:enumeration value="A"></xsd:enumeration>
          </xsd:restriction>
         </xsd:simpleType>
        </xsd:attribute>
        <xsd:attribute name="zoneRuleRef" type="xsd:string"
            use="required" />
    </xsd:complexType>

    <xsd:complexType name="zoneRule">
        <xsd:sequence>
            <xsd:element name="zone" type="dp:zone"
                maxOccurs="unbounded" minOccurs="1" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="exclusivePlacement" type="xsd:boolean"
            use="optional" />
    </xsd:complexType>

    <xsd:complexType name="zone">
        <xsd:attribute name="name" type="xsd:string" use="required" />
    </xsd:complexType>

</xsd:schema>

Entity metadata descriptor XML file

The entity metadata descriptor file is an XML file used to define an entity schema for WebSphere eXtreme Scale. Define all of the entity metadata in the XML file, or define the entity metadata as annotations on the entity Java class file. The primary use is for entities that cannot use Java annotations.

Use XML configuration to create entity metadata that is based on the XML file. When used in conjunction with annotation, some of the attributes that are defined in the XML configuration override the corresponding annotations. If we can override an element, the override is explicitly in the following sections.

id element

The id element implies that the attribute is a key. At a minimum, at least one id element must be specified. We can specify multiple id keys for use as a compound key.

Attributes

name

Name of the attribute. The attribute must exist in the Java file.

alias

Element alias. The alias value is overridden if used in conjunction with an annotated entity.

basic element

The basic element implies that the attribute is a primitive type or wrappers to primitive types:

• java.lang.String
• java.math.BigInteger
• java.math.BigDecimal
• java.util.Date
• java.util.Calendar
• java.sql.Date
• java.sql.Time
• java.sql.Timestamp
• byte[]
• Byte[]
• char[]
• Character[]
• Java Platform, Standard Edition Version 5 enum

It is not necessary to specify any attribute as basic. The basic element attributes are automatically configured using reflection.

Attributes

name

Name of the attribute in the class.

alias

Element alias. The alias value is overridden if used in conjunction with an annotated entity.

fetch

Specifies the fetch type. Valid values include: 

LAZY or EAGER.

id-class element

The id_class element specifies a compound key class, which helps to find entities with compound keys.

Attributes

class-name

Class name, which is an id-class, to use with the id-class element.

transient element

The transient element implies that it is ignored and not processed. It also can be overridden if used in conjunction with annotated entities.

Attributes

name

Name of the attribute, which is ignored.

version element

Attributes

name

Name of the attribute, which is ignored.

cascade-type element

Child elements

• cascade-all: Cascades the all operation to associations.
• cascade-persist: Cascades the persist operation to associations.
• cascade-remove: Cascades the remove operation to associations.
• cascade-merge: Currently not used.
• cascade-refresh: Currently not used.

one-to-one element

Attributes

name

Name of the class, which has a one-to-one relationship.

alias

Specifies a name alias.

target-entity

Association class. This value is a fully-qualified class name.

fetch

Specifies the fetch type. Valid values include: 

LAZY or EAGER.

mapped-by

Specifies the field that owns the relationship. The mapped-by element is only specified on the inverse (non-owning) side of the association.

id

Identifies the association as key.

Child elements

• cascade: cascade-type element

one-to-many element

Attributes

name

Name of the attribute in the class.

alias

Specifies a name alias.

target-entity

Association class. This value is a fully-qualified class name.

fetch

Specifies the fetch type. Valid values include: 

LAZY or EAGER.

mapped-by

Specifies the field that owns the relationship. The mapped-by element is only specified on the inverse (non-owning) side of the association.

Child elements

• order-by
• cascade: cascade-type element

many-to-one element

Attributes

name

Name of the attribute in the class.

alias

Specifies a name alias.

target-entity

Class to which this attribute refers. This value is a fully-qualified class name.

fetch

Specifies the fetch type. Valid values include: 

LAZY or EAGER.

id

Identifies the association as a key.

Child elements

• cascade: cascade-type element

many-to-many element

Attributes

name

Name of the attribute in the class.

alias

Specifies a name alias.

target-entity

Class to which this attribute refers. This value is a fully-qualified class name.

fetch

Specifies the fetch type. Valid values include: 

LAZY or EAGER.

mapped-by

Specifies the field that owns the relationship. The mapped-by element is only specified on the inverse (non-owning) side of the association.

Child elements

• order-by
• cascade: cascade-type element

attributes element

Child elements

• id element
• basic element
• version element
• many-to-one element
• one-to-many element
• one-to-one element
• many-to-many element
• transient element

Entity element

Attributes

name(required)

Name of the attribute in the class.

class-name

Specifies the fully-qualified class name.

access

Access type. The valid values are

PROPERTY or FIELD.

schemaRoot

Specifies that this entity is the schema root and is used as a parent class for partitioned data.

Child elements

• description: Specifies a description.
• id-class element
• attributes element

entity-mappings element

Child elements

• description: Specifies a description.
• Entity element

entity-listener element

Attributes

class-name (required)

Name of the listener class.

Child elements

• PrePersist element
• PostPersist element
• PreRemove element
• PreUpdate element
• PostUpdate element
• PostLoad element

PrePersist element

Attributes

method-name (required)

Lifecycle callback method for the PrePersist event.

PostPersist element

Attributes

method-name (required)

Lifecycle callback method for the PostPersist event.

PreRemove element

Attributes

method-name (required)

Lifecycle callback method for the PreRemove event.

PreUpdate element

Attributes

method-name (required)

Lifecycle callback method for the PreUpdate event.

PostUpdate element

Attributes

method-name (required)

Lifecycle callback method for the PostUpdate event.

PostLoad element

Attributes

method-name (required)

Lifecycle callback method for the PostLoad event.

emd.xsd file

Use the entity metadata XML schema definition to create a descriptor XML file and define an entity schema for WebSphere eXtreme Scale.

emd.xsd file

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:emd="http://ibm.com/ws/projector/config/emd"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://ibm.com/ws/projector/config/emd"
    elementFormfalse ="qualified" attributeFormfalse ="unqualified"
    version="1.0">

    <!-- **************************************************** -->
    <xsd:element name="entity-mappings">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="description" type="xsd:string" minOccurs="0" />
                <xsd:element name="entity" type="emd:entity" minOccurs="1" maxOccurs="unbounded" />
            </xsd:sequence>
        </xsd:complexType>
        <xsd:unique name="uniqueEntityClassName">
            <xsd:selector xpath="emd:entity" />
            <xsd:field xpath="@class-name" />
        </xsd:unique>
    </xsd:element>

    <!-- **************************************************** -->
    <xsd:complexType name="entity">
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string" minOccurs="0" />
            <xsd:element name="id-class" type="emd:id-class" minOccurs="0" />
            <xsd:element name="attributes" type="emd:attributes" minOccurs="0" />
            <xsd:element name="entity-listeners" type="emd:entity-listeners" minOccurs="0" />
            <xsd:element name="pre-persist" type="emd:pre-persist" minOccurs="0" />
            <xsd:element name="post-persist" type="emd:post-persist" minOccurs="0" />
            <xsd:element name="pre-remove" type="emd:pre-remove" minOccurs="0" />
            <xsd:element name="post-remove" type="emd:post-remove" minOccurs="0" />
            <xsd:element name="pre-invalidate" type="emd:pre-invalidate" minOccurs="0" />
            <xsd:element name="post-invalidate" type="emd:post-invalidate" minOccurs="0" />
            <xsd:element name="pre-update" type="emd:pre-update" minOccurs="0" />
            <xsd:element name="post-update" type="emd:post-update" minOccurs="0" />
            <xsd:element name="post-load" type="emd:post-load" minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="class-name" type="xsd:string" use="required" />
        <xsd:attribute name="access" type="emd:access-type" />
        <xsd:attribute name="schemaRoot" type="xsd:boolean" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="attributes">
        <xsd:sequence>
            <xsd:choice>
                <xsd:element name="id" type="emd:id" minOccurs="0" maxOccurs="unbounded" />
            </xsd:choice>
            <xsd:element name="basic" type="emd:basic" minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="version" type="emd:version" minOccurs="0" maxOccurs="unbounded"/>
            <xsd:element name="many-to-one" type="emd:many-to-one" minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="one-to-many" type="emd:one-to-many" minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="one-to-one" type="emd:one-to-one" minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="many-to-many" type="emd:many-to-many" minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="transient" type="emd:transient" minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:simpleType name="access-type">
        <xsd:restriction base="xsd:token">
            <xsd:enumeration value="PROPERTY" />
            <xsd:enumeration value="FIELD" />
        </xsd:restriction>
    </xsd:simpleType>

    <!-- **************************************************** -->
    <xsd:complexType name="id-class">
        <xsd:attribute name="class-name" type="xsd:string" use="required" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="id">
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="type" type="xsd:string" />
        <xsd:attribute name="alias" type="xsd:string" use="optional" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="transient">
        <xsd:attribute name="name" type="xsd:string" use="required" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="basic">
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="alias" type="xsd:string" />
        <xsd:attribute name="type" type="xsd:string" />
        <xsd:attribute name="fetch" type="emd:fetch-type" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:simpleType name="fetch-type">
        <xsd:restriction base="xsd:token">
            <xsd:enumeration value="LAZY" />
            <xsd:enumeration value="EAGER" />
        </xsd:restriction>
    </xsd:simpleType>

    <!-- **************************************************** -->
    <xsd:complexType name="many-to-one">
        <xsd:sequence>
            <xsd:element name="cascade" type="emd:cascade-type" minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="alias" type="xsd:string" />
        <xsd:attribute name="target-entity" type="xsd:string" />
        <xsd:attribute name="fetch" type="emd:fetch-type" />
        <xsd:attribute name="id" type="xsd:boolean" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="one-to-one">
        <xsd:sequence>
            <xsd:element name="cascade" type="emd:cascade-type" minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="alias" type="xsd:string" />
        <xsd:attribute name="target-entity" type="xsd:string" />
        <xsd:attribute name="fetch" type="emd:fetch-type" />
        <xsd:attribute name="mapped-by" type="xsd:string" />
        <xsd:attribute name="id" type="xsd:boolean" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="one-to-many">
        <xsd:sequence>
            <xsd:element name="order-by" type="emd:order-by" minOccurs="0" />
            <xsd:element name="cascade" type="emd:cascade-type" minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="alias" type="xsd:string" />
        <xsd:attribute name="target-entity" type="xsd:string" />
        <xsd:attribute name="fetch" type="emd:fetch-type" />
        <xsd:attribute name="mapped-by" type="xsd:string" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="many-to-many">
        <xsd:sequence>
            <xsd:element name="order-by" type="emd:order-by" minOccurs="0" />
            <xsd:element name="cascade" type="emd:cascade-type" minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="alias" type="xsd:string" />
        <xsd:attribute name="target-entity" type="xsd:string" />
        <xsd:attribute name="fetch" type="emd:fetch-type" />
        <xsd:attribute name="mapped-by" type="xsd:string" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:simpleType name="order-by">
        <xsd:restriction base="xsd:string" />
    </xsd:simpleType>

    <!-- **************************************************** -->
    <xsd:complexType name="cascade-type">
        <xsd:sequence>
            <xsd:element name="cascade-all" type="emd:emptyType" minOccurs="0" />
            <xsd:element name="cascade-persist" type="emd:emptyType" minOccurs="0" />
            <xsd:element name="cascade-remove" type="emd:emptyType" minOccurs="0" />
            <xsd:element name="cascade-invalidate" type="emd:emptyType" minOccurs="0" />
            <xsd:element name="cascade-merge" type="emd:emptyType" minOccurs="0" />
            <xsd:element name="cascade-refresh" type="emd:emptyType" minOccurs="0" />
        </xsd:sequence>
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="emptyType" />

    <!-- **************************************************** -->
    <xsd:complexType name="version">
          <xsd:attribute name="name" type="xsd:string" use="required"/>
          <xsd:attribute name="alias" type="xsd:string" />
          <xsd:attribute name="type" type="xsd:string" />
    </xsd:complexType>

    <!-- **************************************************** -->

    <xsd:complexType name="entity-listeners">
        <xsd:sequence>
            <xsd:element name="entity-listener" type="emd:entity-listener" minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="entity-listener">
        <xsd:sequence>
            <xsd:element name="pre-persist" type="emd:pre-persist" minOccurs="0" />
            <xsd:element name="post-persist" type="emd:post-persist" minOccurs="0" />
            <xsd:element name="pre-remove" type="emd:pre-remove" minOccurs="0" />
            <xsd:element name="post-remove" type="emd:post-remove" minOccurs="0" />
            <xsd:element name="pre-invalidate" type="emd:pre-invalidate" minOccurs="0" />
            <xsd:element name="post-invalidate" type="emd:post-invalidate" minOccurs="0" />
            <xsd:element name="pre-update" type="emd:pre-update" minOccurs="0" />
            <xsd:element name="post-update" type="emd:post-update" minOccurs="0" />
            <xsd:element name="post-load" type="emd:post-load" minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="class-name" type="xsd:string" use="required" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="pre-persist">
        <xsd:attribute name="method-name" type="xsd:string" use="required" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="post-persist">
        <xsd:attribute name="method-name" type="xsd:string" use="required" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="pre-remove">
        <xsd:attribute name="method-name" type="xsd:string" use="required" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="post-remove">
        <xsd:attribute name="method-name" type="xsd:string" use="required" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="pre-invalidate">
        <xsd:attribute name="method-name" type="xsd:string" use="required" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="post-invalidate">
        <xsd:attribute name="method-name" type="xsd:string" use="required" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="pre-update">
        <xsd:attribute name="method-name" type="xsd:string" use="required" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="post-update">
        <xsd:attribute name="method-name" type="xsd:string" use="required" />
    </xsd:complexType>

    <!-- **************************************************** -->
    <xsd:complexType name="post-load">
        <xsd:attribute name="method-name" type="xsd:string" use="required" />
    </xsd:complexType>

</xsd:schema>

Security descriptor XML file

Use a security descriptor XML file to configure a WXS deployment topology with security enabled. Use the elements in this file to configure different aspects of security.

securityConfig element

The securityConfig element is the top-level element of the ObjectGrid security XML file. This element sets up the namespace of the file and the schema location. The schema is defined in the objectGridSecurity.xsd file.

• Number of occurrences: One
• Child elements: security

security element

Use the security element to define an ObjectGrid security.

• Number of occurrences: One
• Child elements: authenticator, adminAuthorization, and systemCredentialGenerator

Attributes

securityEnabled

Enables security for the grid when set to true. The default value is false. If the value is set to false, grid-wide security is disabled. For more information, see Data grid security . (Optional)

singleSignOnEnabled

Enables a client to connect to any server after it has authenticated with one of the servers when the value is set to true. Otherwise, a client must authenticate with each server before the client can connect. The default value is false. (Optional)

loginSessionExpirationTime

Amount of time in seconds before the login session expires. If the login session expires, the client must authenticate again. (Optional)

adminAuthorizationEnabled

Enables administrative authorization. If the value is set to true, all of the administrative tasks need authorization. The authorization mechanism used is specified by the value of the adminAuthorizationMechanism attribute. The default value is false. (Optional)

adminAuthorizationMechanism

Indicates which authorization mechanism to use. WebSphere eXtreme Scale supports two authorization mechanisms, Java Authentication and Authorization Service (JAAS) and custom authorization. The JAAS authorization mechanism uses the standard JAAS policy-based approach. To specify JAAS as the authorization mechanism, set the value to AUTHORIZATION_MECHANISM_JAAS. The custom authorization mechanism uses a user-plugged-in AdminAuthorization implementation. To specify a custom authorization mechanism, set the value to AUTHORIZATION_MECHANISM_CUSTOM. For more information on how these two mechanisms are used, see Authorizing application clients . (Optional)

The following security.xml file is a sample configuration to enable the data grid security.

security.xml

<?xml version="1.0" encoding="UTF-8"?>
<securityConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://ibm.com/ws/objectgrid/config/security ../objectGridSecurity.xsd"
 xmlns="http://ibm.com/ws/objectgrid/config/security">

    <security securityEnabled="true" singleSignOnEnabled="true" 
        loginSessionExpirationTime="20"
        adminAuthorizationEnabled="true"
        adminAuthorizationMechanism="AUTHORIZATION_MECHANISM_JAAS" >
 
        <authenticator className ="com.ibm.websphere.objectgrid.security.plugins.
      builtins.WSTokenAuthenticator">
        </authenticator>
        
        <systemCredentialGenerator className ="com.ibm.websphere.objectgrid.security.
      plugins.builtins.WSTokenCredentialGenerator">
            <property name="properties" type="java.lang.String" value="runAs"
        description="Using runAs subject" />
        </systemCredentialGenerator>

    </security>
</securityConfig>

authenticator element

Authenticates clients to WXS servers in the data grid. The class specified by the className attribute must implement the com.ibm.websphere.objectgrid.security.plugins.Authenticator interface. The authenticator can use properties to call methods on the class specified by the className attribute. See property element for more information on using properties.

In the previous security.xml file example, the com.ibm.websphere.objectgrid.security.plugins.builtins.WSTokenAuthenticator class is specified as the authenticator. This class implements the com.ibm.websphere.objectgrid.security.plugins.Authenticator interface.

• Number of occurrences: zero or one
• Child element: property

Attributes

className

Specifies a class that implements the com.ibm.websphere.objectgrid.security.plugins.Authenticator interface. Use this class to authenticate clients to the servers in the eXtreme Scale grid. (Required)

adminAuthorization element

Use the adminAuthorization element to set up administrative access to the data grid.

• Number of occurrences: zero or one
• Child element: property

Attributes

className

Specifies a class that implements the com.ibm.websphere.objectgrid.security.plugins.AdminAuthorization interface. (Required)

systemCredentialGenerator element

Use a systemCredentialGenerator element to set up a system credential generator. This element only applies to a dynamic environment. In the dynamic configuration model, the dynamic container server connects to the catalog server as a WXS client and the catalog server can connect to the eXtreme Scale container server as a client too. This system credential generator is used to represent a factory for the system credential.

• Number of occurrences: zero or one
• Child element: property

Attributes

className

Specifies a class that implements the com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator interface. (Required)

In this example, the system credential generator is a com.ibm.websphere.objectgrid.security.plugins.builtins.WSTokenCredentialGenerator class, which retrieves the RunAs Subject object from the thread.

property element

Calls set methods on the authenticator and adminAuthorization classes. The name of the property corresponds to a set method on the className attribute of the authenticator or adminAuthorization element.

• Number of occurrences: zero or more
• Child element: property

Attributes

name

Name of the property. The value that is assigned to this attribute must correspond to a set method on the class that is provided as the className attribute on the containing bean. For example, if the className attribute of the bean is set to com.ibm.MyPlugin, and the name of the property that is provided is size, then the com.ibm.MyPlugin class must have a setSize method. (Required)

type

Type of the property. The type of the parameter is passed to the set method that is identified by the name attribute. The valid values are the Java primitives, their java.lang counterparts, and java.lang.String. The name and type attributes must correspond to a method signature on the className attribute of the bean. If the name is size and the type is int, then a setSize(int) method must exist on the class specified as the className attribute for the bean. (Required)

value

Specifies the value of the property. This value is converted to the type specified by the type attribute, and is then used as a parameter in the call to the set method that is identified by the name and type attributes. The value of this attribute is not validated in any way. The plug-in implementor must verify that the value passed in is valid. (Required)

description

Provides a description of the property. (Optional)

objectGridSecurity.xsd file

Use the following ObjectGrid security XML schema to enable security.

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:cc="http://ibm.com/ws/objectgrid/config/security"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 targetNamespace="http://ibm.com/ws/objectgrid/config/security"
 elementFormfalse ="qualified">

 <xsd:element name="securityConfig">
  <xsd:complexType>
   <xsd:sequence>
    <xsd:element name="security" type="cc:security" />
   </xsd:sequence>
  </xsd:complexType>
 </xsd:element>

 <xsd:complexType name="security">
  <xsd:sequence>
   <xsd:element name="authenticator" type="cc:bean" minOccurs="0" 
    maxOccurs="1" />
   <xsd:element name="adminAuthorization" type="cc:bean" minOccurs="0" 
    maxOccurs="1" />
   <xsd:element name="systemCredentialGenerator" type="cc:bean" minOccurs="0" 
    maxOccurs="1" />
  </xsd:sequence>
  <xsd:attribute name="securityEnabled" type="xsd:boolean" use="optional" />
  <xsd:attribute name="singleSignOnEnabled" type="xsd:boolean" use="optional"/>
  <xsd:attribute name="loginSessionExpirationTime" type="xsd:int" use="optional"/>
  <xsd:attribute name="adminAuthorizationMechanism" type="cc:adminAuthorizationMechanism" 
   use="optional"/>
  <xsd:attribute name="adminAuthorizationEnabled" type="xsd:boolean" use="optional" />
 </xsd:complexType>

 <xsd:complexType name="bean">
  <xsd:sequence>
   <xsd:element name="property" type="cc:property" maxOccurs="unbounded" minOccurs="0" />
  </xsd:sequence>
  <xsd:attribute name="className" type="xsd:string" use="required" />
 </xsd:complexType>

 <xsd:complexType name="property">
  <xsd:attribute name="name" type="xsd:string" use="required" />
  <xsd:attribute name="value" type="xsd:string" use="required" />
  <xsd:attribute name="type" type="cc:propertyType" use="required" />
  <xsd:attribute name="description" type="xsd:string" use="optional" />
 </xsd:complexType>

 <xsd:simpleType name="propertyType">
  <xsd:restriction base="xsd:string">
   <xsd:enumeration value="java.lang.Boolean" />
   <xsd:enumeration value="boolean" />
   <xsd:enumeration value="java.lang.String" />
   <xsd:enumeration value="java.lang.Integer" />
   <xsd:enumeration value="int" />
   <xsd:enumeration value="java.lang.Double" />
   <xsd:enumeration value="double" />
   <xsd:enumeration value="java.lang.Byte" />
   <xsd:enumeration value="byte" />
   <xsd:enumeration value="java.lang.Short" />
   <xsd:enumeration value="short" />
   <xsd:enumeration value="java.lang.Long" />
   <xsd:enumeration value="long" />
   <xsd:enumeration value="java.lang.Float" />
   <xsd:enumeration value="float" />
   <xsd:enumeration value="java.lang.Character" />
   <xsd:enumeration value="char" />
  </xsd:restriction>
 </xsd:simpleType>
 
 <xsd:simpleType name="adminAuthorizationMechanism">
  <xsd:restriction base="xsd:string">
   <xsd:enumeration value="AUTHORIZATION_MECHANISM_JAAS" />
   <xsd:enumeration value="AUTHORIZATION_MECHANISM_CUSTOM" />
  </xsd:restriction>
 </xsd:simpleType>

</xsd:schema>

Spring descriptor XML file

Use a Spring descriptor XML file to configure and integrate eXtreme Scale with Spring.

In the following sections, each element and attribute of the Spring objectgrid.xsd file is defined. The Spring objectgrid.xsd file is in the ogspring.jar file and the ObjectGrid namespace com/ibm/ws/objectgrid/spring/namespace.

register element

Use the register element to register the default bean factory for the ObjectGrid.

• Number of occurrences: Zero to many
• Child element: None

Attributes

id

Name of the default bean directory for a particular ObjectGrid.

gridname

Name of the ObjectGrid instance. The value assigned to this attribute must correspond to a valid ObjectGrid configured in the ObjectGrid descriptor file.

<register id="register id"
 gridname="ObjectGrid name"
/>

server element

Use the server element to define a server, which can host a container, a catalog service, or both.

• Number of occurrences: Zero to many
• Child element: None

Attributes

id

Name of the eXtreme Scale server.

tracespec

Indicates the type of trace and enables trace and trace specification for the server.

tracefile

Provides the path and name of the trace file to create and use.

statspec

Indicates the statistic specification for the server.

jmxport

Port number the high availability manager uses. If this property is not set, a free port is chosen. This property is ignored in WebSphere Application Server environments.

isCatalog

Specifies whether the particular server hosts a catalog service. The default value is false.

name

Name of the server.

haManagerPort

Port number the high availability manager uses. If this property is not set, a free port is chosen. This property is ignored in WebSphere Application Server environments.

listenerHost

Host name to which the Object Request Broker (ORB) or eXtremeIO (XIO) transport binds for communication. The value must be a fully-qualified domain name or IP address. If the configuration involves multiple network cards, set the listener host and port to let the transport mechanism in the JVM know the IP address for which to bind. If you do not specify which IP address to use, symptoms such as connection timeouts, unusual API failures, and clients that seem to hang can occur.

listenerPort

Port number to which the Object Request Broker (ORB) or eXtremeIO (XIO) transport binds. This setting configures containers and clients to communicate with the catalog service. In WebSphere Application Server, the listenerPort is inherited by the BOOTSTRAP_ADDRESS port (when we are using the ORB transport) or the XIO_address port (when we are using XIO transport) port configuration. This property applies to both the container server and the catalog service.

maximumThreadPoolSize

Set the maximum number of threads in the pool.

memoryThresholdPercentage

Set the memory threshold (percentage of max heap) for memory-based eviction.

minimumThreadPoolSize

Set the minimum number of threads in the pool.

workingDirectory

The property that defines which directory the ObjectGrid server uses for all default settings.

zoneName

Defines the zone to which this server belongs.

enableSystemStreamToFile

Defines whether SystemOut and SystemErr is sent to a file.

enableMBeans

Determines whether the ObjectGrid registers MBeans in this process.

serverPropertyFile

Loads the server properties from a file.

catalogServerProperties

Catalog server that hosts server.

<server id="server id"
 tracespec="the server trace specification"
 tracefile="the server trace file"
 statspec="the server statistic specification"
 jmxport="JMX port number"
 isCatalog="true"|.false.
 name="the server name.
 haManagerPort="the haManager port"
  listenerHost="the orb binding host name"
  listenerPort="the orb binding listener port"
  maximumThreadPoolSize="the number of maximum threads"
  memoryThresholdPercentage="the memory threshold (percentage of max heap)"
  minimumThreadPoolSize="the number of minimum threads"
 workingDirectory="location for the working directory"
 zoneName="the zone name"
 enableSystemStreamToFile="true"|.false.
 enableMBeans="true"|.false.
 serverPropertyFile="location of the server properties file."
 catalogServerProperties="the catalog server properties reference"
/>

catalog element

Use the catalog element to route to container servers in the data grid.

• Number of occurrences: Zero to many
• Child element: None

Attributes

host

Host name of the workstation where the catalog service is running.

port

Port number paired with the host name to determine the catalog service port to which the client can connect.

<catalog host="catalog service host name"
 port="catalog service port number"
/>

catalogServerProperties element

Use the catalog server properties element to define a catalog service.

• Number of occurrences: Zero to many
• Child element: foreignDomains element

Attributes

catalogServerEndPoint

Connection properties for the catalog server.

enableQuorum

Determines whether to enable quorum.

heartBeatFrequencyLevel

Set the heartbeat frequency level.

domainName

Defines the domain name used to uniquely identify this catalog service domain to clients when routing to multiple catalog service domains.

clusterSecurityURL

Set the location of the security file specific to the catalog service.

<catalogServerProperties catalogServerEndPoint="a catalog server endpoint reference"
 enableQuorum="true"|"false"
 heartBeatFrequencyLevel="
  HEARTBEAT_FREQUENCY_LEVEL_TYPICAL|
  HEARTBEAT_FREQUENCY_LEVEL_RELAXED|
  HEARTBEAT_FREQUENCY_LEVEL_AGGRESSIVE"
 domainName="the domain name used to uniquely identify this catalog service domain"
  clusterSecurityURL="the The cluster security file location.">
 <foreignDomains>
  <foreignDomain name="name_of_foreign_domain_1">
   <endPoint host="catalog server host 1" port="2809"/>
   <endPoint host="catalog server host 2" port="2809"/>
  </foreignDomain>
  <foreignDomain name="name_of_foreign_domain_2">
   <endPoint host="catalog server host 3" port="2809"/>
   <endPoint host="catalog server host 4" port="2809"/>
  </foreignDomain>
 </foreignDomains>
</catalogServerProperties>

foreignDomains element

Use the foreignDomains element to connect to a list of other catalog service domains. Include the name of each catalog service domain and the end points for the catalog servers within each catalog service domain.

• Number of occurrences: Zero to many
• Parent element: catalogServerProperties element
• Child element: foreignDomain element

foreignDomain element

Indicates the name of the catalog service domain to connect. This name is defined with the domainName attribute on the catalogServiceProperties element.

• Number of occurrences: One to many
• Parent element: foreignDomains element
• Child element: endPoint element
• Attributes

  name

  Name that identifies the foreign catalog service domain.

endPoint element

Indicates a list of catalog service end points for a specified foreign catalog service domain.

• Number of occurrences: One to many
• Parent element: foreignDomain element
• Child element: None
• Attributes

  host

  Host name of one of the catalog servers in the catalog service domain.

  port

  Port of one of the catalog servers in the catalog service domain.

catalog server endpoint element

Use the catalog server endpoint element to create a catalog server endpoint to be used by a catalog server element.

• Number of occurrences: Zero to many
• Child element: None

Attributes

serverName

Name that identifies the process that we are launching.

hostName

Host name for the machine where the server is launched.

clientPort

Port used for peer catalog cluster communication.

peerPort

Port used for peer catalog cluster communication.

<catalogServerEndPoint name="catalog server endpoint name"
 host=""
 clientPort=""
 peerPort=""
/>

container element

Use the container element to store the data itself.

• Number of occurrences: Zero to many
• Child element: None

Attributes

objectgridxml

Path and name of the descriptor XML file to use that specifies characteristics for the ObjectGrid, including maps, locking strategy, and plug-ins.

deploymentxml

Path and name of the XML file used with the descriptor XML file. This file determines partitioning, replication, number of initial containers, and other settings.

server

Server on which the container is hosted.

<server objectgridxml="the objectgrid descriptor XML file"
 deploymentxml ="the objectgrid deployment descriptor XML file "
 server="the server reference "
/>

JPALoader element

Use the JPALoader element to synchronize the ObjectGrid cache with an existing backend data store when using the ObjectMap API.

• Number of occurrences: Zero to many
• Child element: None

Attributes

entityClassName

Enables usage of JPAs such as EntityManager.persist and EntityManager.find. The entityClassName attribute is required for the JPALoader.

preloadPartition

Partition number at which the map preload is started. If the value is less than 0, or greater than (totalNumberOfPartition . 1), the map preload is not started.

<JPALoader entityClassName="the entity class name"
 preloadPartition ="int"
/>

JPATxCallback element

Use the JPATxCallback element to coordinate JPA and ObjectGrid transactions.

• Number of occurrences: Zero to many
• Child element: None

Attributes

persistenceUnitName

Creates a JPA EntityManagerFactory and locates the JPA entity metadata in the persistence.xml file. The persistenceUnitName attribute is required.

jpaPropertyFactory

Specifies the factory to create a persistence property map to override the default persistence properties. This attribute references a bean.

exceptionMapper

Specifies the ExceptionMapper plug-in that can be used for JPA-specific or database-specific exception mapping functions. This attribute references a bean.

<JPATxCallback persistenceUnitName="the JPA persistence unit name"
 jpaPropertyFactory ="JPAPropertyFactory bean reference"
 exceptionMapper="ExceptionMapper bean reference"
/>

JPAEntityLoader element

Use the JPAEntityLoader element to synchronize the ObjectGrid cache with an existing backend data store when using the EntityManager API.

• Number of occurrences: Zero to many
• Child element: None

Attributes

entityClassName

Enables usage of JPAs such as EntityManager.persist and EntityManager.find. The entityClassName attribute is optional for the JPAEntityLoader element. If the element is not configured, the entity class configured in the ObjectGrid entity map is used. The same class must be used for the ObjectGrid EntityManager and for the JPA provider.

preloadPartition

Partition number at which the map preload is started. If the value is less than 0, or greater than (totalNumberOfPartition . 1) the map preload is not launched.

<JPAEntityLoader entityClassName="the entity class name"
 preloadPartition ="int"
/>

LRUEvictor element

Use the LRUEvictor element to decide which entries to evict when a map exceeds its maximum number of entries.

• Number of occurrences: Zero to many
• Child element: None

Attributes

maxSize

Total entries in a queue until the evictor must intervene.

sleepTime

Time in seconds between the eviction sweep over map queues to determine any necessary actions on the map.

numberOfLRUQueues

Setting of how many queues the evictor must scan to avoid having a single queue that is the size of the entire map.

<LRUEvictor maxSize="int"
 sleepTime ="seconds"
 numberOfLRUQueues ="int"
/>

LFUEvictor element

Use the LFUEvictor element to determine which entries to evict when a map exceeds its maximum number of entries.

• Number of occurrences: Zero to many
• Child element: None

Attributes

maxSize

Total entries that are allowed in each heap until the evictor must act.

sleepTime

Time in seconds between eviction sweeps over map heaps to determine any necessary actions on the map.

numberOfHeaps

Setting of how many heaps the evictor must scan to avoid having a single heap that is the size of the entire map.

<LFUEvictor maxSize="int"
 sleepTime ="seconds"
 numberOfHeaps ="int"
/>

HashIndex element

Use the HashIndex element with Java reflection to dynamically introspect objects stored in a map when the objects are updated.

• Number of occurrences: Zero to many
• Child element: None

Attributes

name

Name of the index, which must be unique for each map.

attributeName

Name of the attribute to index. For field-access indexes, the attribute name is equivalent to the field name. For property-access indexes, the attribute name is the JavaBeans compatible property name.

rangeIndex

Indicates whether range indexing is enabled. The default value is false.

fieldAccessAttribute

Used for non-entity maps. The getter method is used to access the data. The default value is false. If you specify the value as true, the object is accessed using the fields directly.

POJOKeyIndex

Used for non-entity maps. The default value is false. If you specify the value as true, the index introspects the object in the key part of the map. This inspection is useful when the key is a composite key and the value does not have an embedded key. If you do not set the value or you specify the value as false, the index introspects the object in the value part of the map.

<HashIndex name="index name"
 attributeName="attribute name"
 rangeIndex ="true"|"false"
 fieldAccessAttribute ="true"|"false"
 POJOKeyIndex ="true"|"false"
/>

Spring objectgrid.xsd file

Use the Spring objectgrid.xsd file to integrate eXtreme Scale with Spring to manage eXtreme Scale transactions and configure clients and servers.

Spring objectgrid.xsd file

<xsd:schema xmlns="http://www.ibm.com/schema/objectgrid"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://www.ibm.com/schema/objectgrid"
    elementFormfalse ="qualified"
    attributeFormfalse ="unqualified">

    <xsd:element name="transactionManager">
      <xsd:complexType>
         <xsd:attribute name="id" type="xsd:ID"/>
      </xsd:complexType>
   </xsd:element>

    <xsd:element name="register">
      <xsd:complexType>
         <xsd:attribute name="id" type="xsd:ID"/>
         <xsd:attribute name="gridname" type="xsd:string"/>
      </xsd:complexType>
   </xsd:element>

    <xsd:element name="server">
      <xsd:complexType>
        <xsd:sequence>
            <xsd:element name="catalog" minOccurs="0" maxOccurs="unbounded">
                <xsd:complexType>
                    <xsd:attribute name="host" type="xsd:string" />
                    <xsd:attribute name="port" type="xsd:integer" />
                </xsd:complexType>
            </xsd:element>
            <xsd:element name="xioChannel" minOccurs="0" maxOccurs="unbounded">
                <xsd:complexType>
                    <xsd:sequence minOccurs="1" maxOccurs="unbounded">
                        <xsd:element ref="property" />
                    </xsd:sequence>
                    <xsd:attribute name="name" type="xsd:string" />
                </xsd:complexType>
            </xsd:element>
        </xsd:sequence>
         <xsd:attribute name="id" type="xsd:ID"/>
         <xsd:attribute name="tracespec" type="xsd:string"/>
         <xsd:attribute name="tracefile" type="xsd:string"/>
         <xsd:attribute name="statspec" type="xsd:string"/>
         <xsd:attribute name="logNotificationFilter" type="xsd:string"/>
         <xsd:attribute name="jmxport" type="xsd:integer"/>
         <xsd:attribute name="isCatalog" type="xsd:boolean"/>
         <xsd:attribute name="name" type="xsd:string"/>
         <xsd:attribute name="haManagerPort" type="xsd:integer"/>
         <xsd:attribute name="listenerHost" type="xsd:string"/>
         <xsd:attribute name="listenerPort" type="xsd:integer"/>
         <xsd:attribute name="maximumThreadPoolSize" type="xsd:integer"/>
         <xsd:attribute name="memoryThresholdPercentage" type="xsd:integer"/>
         <xsd:attribute name="minimumThreadPoolSize" type="xsd:integer"/>
         <xsd:attribute name="workingDirectory" type="xsd:string"/>
         <xsd:attribute name="zoneName" type="xsd:string"/>
         <xsd:attribute name="enableChannelFramework" type="xsd:boolean"/>
         <xsd:attribute name="enableSystemStreamToFile" type="xsd:boolean"/>
         <xsd:attribute name="enableMBeans" type="xsd:boolean"/>
         <xsd:attribute name="serverPropertyFile" type="xsd:string"/>
         <xsd:attribute name="catalogServerProperties" type="xsd:string"/>
         <xsd:attribute name="jvmStatsLoggingEnabled" type="xsd:boolean"/>
         <xsd:attribute name="maximumJVMStatsFiles" type="xsd:integer"/>
         <xsd:attribute name="maximumJVMStatsFileSize" type="xsd:integer"/>
         <xsd:attribute name="jvmStatsFileName" type="xsd:string"/>
         <xsd:attribute name="jvmStatsWriteRate" type="xsd:integer"/>
         <xsd:attribute name="mapStatsLoggingEnabled" type="xsd:boolean"/>
         <xsd:attribute name="maximumMapStatsFiles" type="xsd:integer"/>
         <xsd:attribute name="maximumMapStatsFileSize" type="xsd:integer"/>
         <xsd:attribute name="mapStatsFileName" type="xsd:string"/>
         <xsd:attribute name="mapStatsWriteRate" type="xsd:integer"/>
         <xsd:attribute name="OGStatsLoggingEnabled" type="xsd:boolean"/>
         <xsd:attribute name="maximumOGStatsFiles" type="xsd:integer"/>
         <xsd:attribute name="maximumOGStatsFileSize" type="xsd:integer"/>
         <xsd:attribute name="OGStatsFileName" type="xsd:string"/>
         <xsd:attribute name="OGStatsWriteRate" type="xsd:integer"/>
         <xsd:attribute name="enableXM" type="xsd:boolean"/>
         <xsd:attribute name="maximumXMSize" type="xsd:integer"/>
         <xsd:attribute name="minimumXIOWorkerThreads" type="xsd:integer"/>
         <xsd:attribute name="maximumXIOWorkerThreads" type="xsd:integer"/>
         <xsd:attribute name="minimumXIONetworkThreads" type="xsd:integer"/>
         <xsd:attribute name="maximumXIONetworkThreads" type="xsd:integer"/>
         <xsd:attribute name="xioTimeout" type="xsd:integer"/>
         <xsd:attribute name="hpelEnabled" type="xsd:boolean"/>
         <xsd:attribute name="hpelEnableBuffering" type="xsd:boolean"/>
         <xsd:attribute name="hpelFileSwitchHour" type="xsd:integer"/>
         <xsd:attribute name="hpelIncludeTrace" type="xsd:boolean"/>
         <xsd:attribute name="hpelMaxRepositorySize" type="xsd:long"/>
         <xsd:attribute name="hpelMaxRetentionTime" type="xsd:long"/>
         <xsd:attribute name="hpelOutOfSpaceAction" type="xsd:string"/>
         <xsd:attribute name="hpelOutputFormat" type="xsd:string"/>
         <xsd:attribute name="hpelEnablePurgeBySize" type="xsd:boolean"/>
         <xsd:attribute name="hpelEnablePurgeByTime" type="xsd:boolean"/>
         <xsd:attribute name="hpelRepositoryPath" type="xsd:string"/>
         <xsd:attribute name="hpelEnableFileSwitch" type="xsd:boolean"/>
      </xsd:complexType>
    </xsd:element>

    <xsd:element name="property">
      <xsd:complexType>
        <xsd:attribute name="name" type="xsd:string"/>
        <xsd:attribute name="value" type="xsd:string"/>
      </xsd:complexType>
    </xsd:element>

    <xsd:element name="catalogServerProperties">
      <xsd:complexType>
        <xsd:sequence>
            <xsd:choice minOccurs="0" maxOccurs="unbounded">
                <xsd:element ref="catalogServerEndPoint" />
            </xsd:choice>
            <xsd:element name="foreignDomains" minOccurs="0"
                maxOccurs="unbounded">
                <xsd:complexType>
                    <xsd:sequence minOccurs="1" maxOccurs="unbounded">
                        <xsd:element ref="foreignDomain" />
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>
        </xsd:sequence>
        <xsd:attribute name="id" type="xsd:ID"/>
        <xsd:attribute name="enableQuorum" type="xsd:boolean"/>
        <xsd:attribute name="enableManagementConcentrator" type="xsd:boolean"/>
        <xsd:attribute name="heartBeatFrequencyLevel" type="xsd:integer"/>
        <xsd:attribute name="domainName" type="xsd:string"/>
        <xsd:attribute name="clusterSecurityURL" type="xsd:anyURI"/>
        <xsd:attribute name="placementDeferralInterval" type="xsd:long"/>
        <xsd:attribute name="transport" type="xsd:string"/>
      </xsd:complexType>
    </xsd:element>

    <xsd:element name="catalogServerEndPoint">
      <xsd:complexType>
        <xsd:attribute name="name" type="xsd:string"/>
        <xsd:attribute name="host" type="xsd:string"/>
        <xsd:attribute name="clientPort" type="xsd:integer"/>
        <xsd:attribute name="peerPort" type="xsd:integer"/>
      </xsd:complexType>
    </xsd:element>

    <xsd:element name="foreignDomain">
        <xsd:complexType>
            <xsd:sequence minOccurs="1" maxOccurs="unbounded">
                <xsd:element ref="foreignDomainEndPoint" />
            </xsd:sequence>
            <xsd:attribute name="name" />
        </xsd:complexType>
    </xsd:element>

    <xsd:element name="foreignDomainEndPoint">
        <xsd:complexType>
            <xsd:attribute name="host" type="xsd:string" />
            <xsd:attribute name="listenerPort" type="xsd:integer" />
        </xsd:complexType>
    </xsd:element>

    <xsd:element name="container">
      <xsd:complexType>
         <xsd:attribute name="id" type="xsd:ID"/>
         <xsd:attribute name="objectgridxml" type="xsd:string"/>
         <xsd:attribute name="deploymentxml" type="xsd:string"/>
         <xsd:attribute name="server" type="xsd:string"/>
      </xsd:complexType>
   </xsd:element>

    <xsd:element name="JPALoader">
      <xsd:complexType>
         <xsd:attribute name="id" type="xsd:ID"/>
         <xsd:attribute name="entityClassName" type="xsd:string"/>
         <xsd:attribute name="preloadPartition" type="xsd:integer"/>
      </xsd:complexType>
   </xsd:element>

   <xsd:element name="JPATxCallback">
      <xsd:complexType>
         <xsd:attribute name="id" type="xsd:ID"/>
         <xsd:attribute name="persistenceUnitName" type="xsd:string"/>
         <xsd:attribute name="jpaPropertyFactory" type="xsd:string"/>
         <xsd:attribute name="exceptionMapper" type="xsd:string"/>
      </xsd:complexType>
   </xsd:element>

   <xsd:element name="JPAEntityLoader">
      <xsd:complexType>
         <xsd:attribute name="id" type="xsd:ID"/>
         <xsd:attribute name="entityClassName" type="xsd:string"/>
         <xsd:attribute name="preloadPartition" type="xsd:integer"/>
      </xsd:complexType>
   </xsd:element>

   <xsd:element name="LRUEvictor">
      <xsd:complexType>
         <xsd:attribute name="id" type="xsd:ID"/>
         <xsd:attribute name="maxSize" type="xsd:integer"/>
         <xsd:attribute name="sleepTime" type="xsd:integer"/>
         <xsd:attribute name="numberOfLRUQueues" type="xsd:integer"/>
         <xsd:attribute name="useMemoryUsageThresholdEviction" type="xsd:boolean"/>
      </xsd:complexType>
   </xsd:element>

   <xsd:element name="LFUEvictor">
      <xsd:complexType>
         <xsd:attribute name="id" type="xsd:ID"/>
         <xsd:attribute name="maxSize" type="xsd:integer"/>
         <xsd:attribute name="sleepTime" type="xsd:integer"/>
         <xsd:attribute name="numberOfHeaps" type="xsd:integer"/>
         <xsd:attribute name="useMemoryUsageThresholdEviction" type="xsd:boolean"/>
      </xsd:complexType>
   </xsd:element>

   <xsd:element name="HashIndex">
      <xsd:complexType>
         <xsd:attribute name="id" type="xsd:ID"/>
         <xsd:attribute name="name" type="xsd:string"/>
         <xsd:attribute name="attributeName" type="xsd:string"/>
         <xsd:attribute name="rangeIndex" type="xsd:boolean"/>
         <xsd:attribute name="fieldAccessAttribute" type="xsd:boolean"/>
         <xsd:attribute name="POJOKeyIndex" type="xsd:boolean"/>
      </xsd:complexType>
   </xsd:element>

   <!-- This element can be removed when Eclipse Gemini correctly supports Blueprint custom scopes -->
   <xsd:attribute name="dummy" type="xsd:boolean"/>

</xsd:schema>

Liberty profile configuration files

We can specify server properties and Liberty web feature properties for WebSphere eXtreme Scale applications that run in the Liberty profile.

Use the following files to configure eXtreme Scale servers that run in the Liberty profile:

Liberty profile server properties

Use the options from the server properties file to configure WebSphere eXtreme Scale servers that run in the Liberty profile.

The server properties file contains several properties that define different settings for your server, such as security configuration. The server properties file is used by both catalog service and container servers in both stand-alone servers and servers hosted in WebSphere Application Server.

Configure server.xml using the same configuration that you might use for a stand-alone server configuration. In server.xml, specify the file path to the properties file in a serverProps attribute inside the com.ibm.ws.xs.server.config element. See the following example from server.xml:

<server>
...
<com.ibm.ws.xs.server.config ... serverProps="/path/to/myServerProps.properties" ... />
</server>

Some properties that were formerly configurable in a stand-alone environment must be configured using the Liberty profile configuration instead of the eXtreme Scale configuration mechanisms.

• Logging and tracing settings must be specified using the logging element in server.xml, rather than being specified in the eXtreme Scale server properties file or com.ibm.ws.xs.server.config element.
• The working directory, like logging and tracing, is a server-wide setting, and therefore, they must be specified in a server-wide way.

If the previous settings are specified incorrectly, eXtreme Scale logs a warning message, which indicates that the settings are ignored.

Liberty profile web feature properties

Specify the web feature for your server definition to identify web-based applications and add functions, such as session replication.

The web feature is deprecated. Use the webApp feature when we want to replicate HTTP session data for fault tolerance. We can set the following attributes on the xsWebApp element of server.xml:

Parameters

objectGridType

A string value that is set to REMOTE, which specifies that session data is stored outside of the server on which the web application is running.

objectGridName

A string value that defines the name of the ObjectGrid instance used for a particular web application. The default name is session.

This property must reflect the objectGridName in both the ObjectGrid XML and deployment XML files used to start the eXtreme Scale container servers.

catalogHostPort

The catalog server can be contacted to obtain a client side ObjectGrid instance. The value must be of the form host:port<,host:port>. The host is the listener host on which the catalog server is running. The port is the listener port for that catalog server process. This list can be arbitrarily long and is used for bootstrapping only. The first viable address is used. It is optional inside WebSphere Application Server if the catalog.services.cluster property is configured.

replicationInterval

An integer value (in seconds) that defines the time between writing of updated sessions to ObjectGrid. The default is

10 seconds. Possible values are from 0 to 60. 0 means that updated sessions are written to the ObjectGrid at the end of servlet service method call for each request. A higher replicationInterval value improves performance because fewer updates are written to the data grid. However, a higher value makes the configuration less fault tolerant.

This setting applies only when objectGridType is set to REMOTE.

sessionTableSize

An integer value that defines the number of session references kept in memory. The default is

1000.

This setting pertains only to a REMOTE topology.

Sessions are evicted from the in-memory table based on least recently used (LRU) logic. When a session is evicted from the in-memory table, it is invalidated from the web container. However, the data is not removed from the grid, so subsequent requests for that session can still retrieve the data. This value must be set higher than the web container maximum thread pool value, which reduces contention on the session cache.

fragmentedSession

A string value of either true or false. Default is true. Use this setting to control whether the product stores session data as a whole entry, or stores each attribute separately.

Set the fragmentedSession parameter to true if the web application session has many attributes or attributes with large sizes. Set fragmentedSession to false if a session has few attributes, because all the attributes are stored in the same key in the data grid.

In the previous, filter-based implementation, this property was referred to as persistenceMechanism, with the possible values of ObjectGridStore (fragmented) and ObjectGridAtomicSessionStore (not fragmented).

securityEnabled

A string value of either true or false. The default value is false. This setting enables eXtreme Scale client security. It must match the securityEnabled setting in the eXtreme Scale server properties file. If the settings do not match, an exception occurs.

credentialAuthentication

Indicates if credential authentication is enforced or supported.

Never

No client certificate authentication is enforced.

Required

Credential authentication is always enforced. If the server does not support credential authentication, the client cannot to connect to the server.

Supported

(false) Credential authentication is enforced only if both the client and server support credential authentication.

authenticationRetryCount

Name of the class that implements the com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator interface. This class is used to get credentials for clients. The default value is

0.

credentialGeneratorClass

The name of the class that implements the com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator interface. This class is used to obtain credentials for clients.

credentialGeneratorProps

The properties for the CredentialGenerator implementation class. The properties are set to the object with the setProperties(String) method. The credentialGeneratorProps value is used only if the value of the credentialGeneratorClass property is not null.

objectGridXML

The file location of the objectgrid.xml file.

objectGridDeploymentXML

Location of the objectGrid deployment policy XML file.

cookieDomain

Specifies if you require sessions to be accessible across hosts. Set the value to the name of the common domain between the hosts.

cookiePath

The default path is

"/".

reuseSessionID

Set to true if the underlying web container reuses session IDs across requests to different hosts. The default value is false. The value of this property must be the same as the value in the web container. If we are using WebSphere Application Server and configuring eXtreme Scale HTTP session persistence using the administrative console or wsadmin tool scripting, the web container custom property

HttpSessionIdReuse=true is added by default. The reuseSessionID is also set to true. If you do not want the session IDs to be reused, set the HttpSessionIdReuse=false custom property on the web container custom property before you configure eXtreme Scale session persistence.

shareSessionsAcrossWebApps

Specifies if sessions are shared across web applications, specified as a string value of either true or false. The default is false. The servlet specification states that HTTP Sessions cannot be shared across web applications. An extension to the servlet specification is provided to allow this sharing.

useURLEncoding

Set to true if we want to enable URL rewriting. The default value is false, which indicates that cookies are used to store session data. The value of this parameter must be the same as the web container settings for session management.

useCookies

The default value is false.

Liberty profile webApp feature properties

Specify the webApp feature to extend the Liberty profile web application. Add the webApp feature when we want to replicate HTTP session data for fault tolerance.

The web feature is deprecated. Use the webApp feature when we want to replicate HTTP session data for fault tolerance. We can set the following attributes on the xsWebApp element of server.xml:

Parameters

objectGridName

A string value that defines the name of the ObjectGrid instance used for a particular web application. The default name is session.

This property must reflect the objectGridName in both the ObjectGrid XML and deployment XML files used to start the eXtreme Scale container servers.

catalogHostPort

The catalog server can be contacted to obtain a client side ObjectGrid instance. The value must be of the form host:port<,host:port>. The host is the listener host on which the catalog server is running. The port is the listener port for that catalog server process. This list can be arbitrarily long and is used for bootstrapping only. The first viable address is used. It is optional inside WebSphere Application Server if the catalog.services.cluster property is configured.

replicationInterval

An integer value (in seconds) that defines the time between writing of updated sessions to ObjectGrid. The default is 10 seconds. Possible values are from 0 to 60. 0 means that updated sessions are written to the ObjectGrid at the end of servlet service method call for each request. A higher replicationInterval value improves performance because fewer updates are written to the data grid. However, a higher value makes the configuration less fault tolerant.

This setting applies only when objectGridType is set to REMOTE.

sessionTableSize

An integer value that defines the number of session references kept in memory. The default is 1000.

This setting pertains only to a REMOTE topology because the EMBEDDED topology already has the session data in the same tier as the web container.

Sessions are evicted from the in-memory table based on least recently used (LRU) logic. When a session is evicted from the in-memory table, it is invalidated from the web container. However, the data is not removed from the grid, so subsequent requests for that session can still retrieve the data. This value must be set higher than the web container maximum thread pool value, which reduces contention on the session cache.

fragmentedSession

A string value of either true or false. Default is true. Use this setting to control whether the product stores session data as a whole entry, or stores each attribute separately.

Set the fragmentedSession parameter to true if the web application session has many attributes or attributes with large sizes. Set fragmentedSession to false if a session has few attributes, because all the attributes are stored in the same key in the data grid.

In the previous, filter-based implementation, this property was referred to as persistenceMechanism, with the possible values of ObjectGridStore (fragmented) and ObjectGridAtomicSessionStore (not fragmented).

securityEnabled

A string value of either true or false. The default value is false. This setting enables eXtreme Scale client security. It must match the securityEnabled setting in the eXtreme Scale server properties file. If the settings do not match, an exception occurs.

credentialAuthentication

Indicates if credential authentication is enforced or supported.

Never

No client certificate authentication is enforced.

Required

Credential authentication is always enforced. If the server does not support credential authentication, the client cannot to connect to the server.

Supported

(false) Credential authentication is enforced only if both the client and server support credential authentication.

authenticationRetryCount

Name of the class that implements the com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator interface. This class is used to get credentials for clients. The default value is

0.

credentialGeneratorClass

The name of the class that implements the com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator interface. This class is used to obtain credentials for clients.

credentialGeneratorProps

The properties for the CredentialGenerator implementation class. The properties are set to the object with the setProperties(String) method. The credentialGeneratorProps value is used only if the value of the credentialGeneratorClass property is not null.

shareSessionsAcrossWebApps

Specifies if sessions are shared across web applications, specified as a string value of either true or false. The default is false. The servlet specification states that HTTP Sessions cannot be shared across web applications. An extension to the servlet specification is provided to allow this sharing.

Liberty profile webGrid feature properties

Specify the webGrid feature to automatically start a container that hosts clients for HTTP session replication.

We can set the following attributes on the xsWebApp element of server.xml:

Parameters

objectGridType

A string value that is set to REMOTE, which specifies that session data is stored outside of the server on which the web application is running.

objectGridName

A string value that defines the name of the ObjectGrid instance used for a particular web application. The default name is session.

This property must reflect the objectGridName in both the ObjectGrid XML and deployment XML files used to start the eXtreme Scale container servers.

catalogHostPort

The catalog server can be contacted to obtain a client side ObjectGrid instance. The value must be of the form host:port<,host:port>. The host is the listener host on which the catalog server is running. The port is the listener port for that catalog server process. This list can be arbitrarily long and is used for bootstrapping only. The first viable address is used. It is optional inside WebSphere Application Server if the catalog.services.cluster property is configured.

fragmentedSession

A string value of either true or false. Default is true. Use this setting to control whether the product stores session data as a whole entry, or stores each attribute separately.

Set the fragmentedSession parameter to true if the web application session has many attributes or attributes with large sizes. Set fragmentedSession to false if a session has few attributes, because all the attributes are stored in the same key in the data grid.

In the previous, filter-based implementation, this property was referred to as persistenceMechanism, with the possible values of ObjectGridStore (fragmented) and ObjectGridAtomicSessionStore (not fragmented).

securityEnabled

A string value of either true or false. The default value is false. This setting enables eXtreme Scale client security. It must match the securityEnabled setting in the eXtreme Scale server properties file. If the settings do not match, an exception occurs.

credentialAuthentication

Indicates if credential authentication is enforced or supported.

Never

No client certificate authentication is enforced.

Required

Credential authentication is always enforced. If the server does not support credential authentication, the client cannot to connect to the server.

Supported

(false) Credential authentication is enforced only if both the client and server support credential authentication.

authenticationRetryCount

Name of the class that implements the com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator interface. This class is used to get credentials for clients. The default value is

0.

credentialGeneratorClass

The name of the class that implements the com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator interface. This class is used to obtain credentials for clients.

credentialGeneratorProps

The properties for the CredentialGenerator implementation class. The properties are set to the object with the setProperties(String) method. The credentialGeneratorProps value is used only if the value of the credentialGeneratorClass property is not null.

objectGridXML

The file location of the objectgrid.xml file. The built-in XML file packaged in the eXtreme Scale library is loaded automatically if

objectGridType=EMBEDDED and the objectGridXML property is not specified.

objectGridDeploymentXML

Location of the objectGrid deployment policy XML file. The built-in XML file packaged in the eXtreme Scale library is loaded automatically if

objectGridType=EMBEDDED and the objectGridDeploymentXML property is not specified.

shareSessionsAcrossWebApps

Specifies if sessions are shared across web applications, specified as a string value of either true or false. The default is false. The servlet specification states that HTTP Sessions cannot be shared across web applications. An extension to the servlet specification is provided to allow this sharing.

ojectGridTxTimeout

Amount of time in seconds that a transaction is allowed for completion. If a transaction does not complete in this amount of time, the transaction is marked for rollback and a TransactionTimeoutException exception results. Default:

30 (in seconds)

mapSetNumberOfPartitions

Number of partitions for the mapSet element. Default: 47

mapSetMinSyncReplicas

Minimum number of synchronous replicas for each partition in the mapSet. Shards are not placed until the domain can support the minimum number of synchronous replicas. To support the minSyncReplicas value, you need one more container server than the minSyncReplicas value. If the number of synchronous replicas falls below the minSyncReplicas value, write transactions are no longer allowed for that partition. Default: 0

mapSetMaxSyncReplicas

Maximum number of synchronous replicas for each partition in the mapSet. No other synchronous replicas are placed for a partition after a domain reaches this number of synchronous replicas for that specific partition. Adding container servers that can support this ObjectGrid can result in an increased number of synchronous replicas if your maxSyncReplicas value has not already been met. Default: 0

mapSetMaxAsyncReplicas

Maximum number of asynchronous replicas for each partition in the mapSet. No other asynchronous replicas are placed for a partition after a domain reaches this number of asynchronous replicas for that specific partition. Adding container servers that can support this ObjectGrid can result in an increased number of asynchronous replicas if your maxAsyncReplicas value has not already been met. Default: 0

mapSetDevelopmentMode

With this attribute, we can influence where a shard is placed in relation to its peer shards. When the developmentMode attribute is set to false, no two shards from the same partition are placed on the same computer. When the developmentMode attribute is set to true, shards from the same partition can be placed on the same machine. In either case, no two shards from the same partition are ever placed in the same container server. Default: false