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. See objectGrid.xsd file for an example of the ObjectGrid descriptor XML schema.
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
- Specifies the 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
- Sets the authorization mechanism for the element. You can set
the attribute to one of two values: AUTHORIZATION_MECHANISM_JAAS or AUTHORIZATION_MECHANISM_CUSTOM. The default
is AUTHORIZATION_MECHANISM_JAAS. You must 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 that is 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. You must 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 you run the
upsert API within your 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
- Specifies the 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)
- txIsolation
- Sets the default transaction isolation level for all sessions
created by the ObjectGrid. Define one of the following values:
- REPEATABLE_READ (default): Specifies that
dirty reads and non-repeatable reads are prevented; phantom reads
can occur. This level prohibits a transaction from reading an uncommitted
cache entry. It also prohibits the following scenario: one transaction
reads an entry, a second transaction alters the entry, and the first
transaction rereads the entry, getting different values the second
time (a "non-repeatable read").
- READ_UNCOMMITTED: Specifies that dirty
reads, non-repeatable reads and phantom reads can occur. Cache entries
can be changed by one transaction and read by another transaction
before any changes in that entry have been committed. If any of the
changes are rolled back, the second transaction retrieves an entry
that is not valid.
- READ_COMMITTED: Specifies that dirty reads
are prevented; non-repeatable reads and phantom reads can occur. This
level only prohibits a transaction from reading a cache entry that
has uncommitted changes.
- entityMetadataXMLFile
- Specifies the 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. For details, see
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 the value to 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
- Sets the 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.
- lockTimeout
- Sets the lock timeout that is 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
- Specifies the name that is assigned to the backingMap instance.
If this attribute is missing, the XML validation fails. (Required)
- nullValuesSupported
- Set the value to 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. The default
value is true. (Optional)
- numberOfBuckets
Deprecated: This property has been deprecated. Use the
nearCacheEnabled attribute to enable the near cache.
The BackingMap instance
uses a hash map for implementation. The numberOfBuckets attribute specifies the number of buckets for the BackingMap instance
to use. 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
- The lock manager uses a hash map to track entries that are locked
by one or more transactions. The numberOfLockBuckets attribute sets the number of lock buckets that are 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. 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
- Sets 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
- Sets 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 that is 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"
/>
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. You 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
- Specifies the 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
- Specifies the 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
- Specifies the 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. See Configuring OSGi-enabled plug-ins using the ObjectGrid descriptor XML file for more information. 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
- Specifies the 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
- Specifies the 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 that is specified as the className attribute
for the bean. (Required)
- value
- Specifies the value of the property. This value is converted to
the type that is 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
- Specifies the name of the BackingMap to add to the schema. (Required)
- valueClass
- Specifies the type of object that is stored in the value portion
of the BackingMap. (Required)
- primaryKeyField
- Specifies the 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
- Specifies the name of the valueClass of the source side of a relationship.
(Required)
- target
- Specifies the name of the valueClass of the target side of a relationship.
(Required)
- relationField
- Specifies the name of the attribute in the source valueClass that
refers to the target. (Required)
- invRelationField
- Specifies the 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
- Specifies the name of the stream. Validation fails if this attribute
is not specified. (Required)
- valueClass
- Specifies the 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
- Specifies the 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 by using the tuple
attributes of the entity metadata. (Optional)
- access
- Specifies the 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
- Specifies the name of the view. Validation fails if this attribute
is not specified. (Required)
- sql
- Specifies the SQL of the stream, which defines the view transformation.
Validation fails if this attribute is not specified. (Required)
- valueClass
- Specifies the 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
- Specifies the 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"
/>