This chapter describes how to configure and manage the Oracle Communications Services Gatekeeper Storage service that communication services use to store data.
Services Gatekeeper Storage service provides transparent data access to communication services and container services. Conceptually, a module uses the Storage service, which in turn uses one or more underlying storage providers that define how and where data is stored. A module creates and uses one or more named stores which can be of different store types. The current storage provider is the Invalidating Storage Provider, an in-memory cache backed by a persistence store, currently a database, acting as the master. The store is a write-through cache. In order to maintain a coherent view of the cache, invalidating events are broadcast within the cluster for specific operations.
For a discussion of which store type to use in a communication service, see ”Understanding Services Gatekeeper Storage Services” in Services Gatekeeper Extension Developer's Guide.
Table 15-1 outlines the store types.
Table 15-1 Services Gatekeeper Store Types
| Type | Description |
|---|---|
|
Cluster cache |
A clusterwide in-memory-only store, ideally with redundancy support by keeping backup copies on one, or more of the other servers in the cluster. This is an in-memory only, so data reads and writes are very fast compared to store types backed up to a database table. However it is less reliable because they are backed up using duplicate copies in process memory. |
|
Write-behind database store |
A clusterwide in-memory cache, ideally with redundancy support implemented by keeping backup copies on one or more of the other servers in the cluster and is also backed by a database. Updates for the database table for write-behind stores are delayed and asynchronously written in batches to the database. This store has similar performance characteristics to the cluster store for data that is available in the cache, but with better availability. It is a good compromise between performance and availability. |
|
Write-through database store |
A clusterwide in-memory cache of a database table. Updates for the database table for write-through stores are synchronous as part of the store update operation. The method invocation is blocked until the database query has been performed. Each data entry in the store is backed up on one other server in the cluster. The data is immediately persisted to the database without delay. Updates to data in the store are slow compared to the cluster store, but read operations are fast if the data is available in cache. This store offers best reliability. |
|
Refresh ahead database store |
This option configures a cache to automatically and asynchronously reload (refresh) any recently accessed cache entry from the cache loader before its expiration. The result is that after a frequently accessed entry has entered the cache, the application does not feel the impact of a read against a potentially slow cache store when the entry is reloaded due to expiration. The asynchronous refresh is only triggered when an object that is sufficiently close to its expiration time is accessed. If the object is accessed after its expiration time, Coherence performs a synchronous read from the cache store to refresh its value. |
|
Database log store |
The log store type data updates to the database table are delayed and asynchronously written in batches to the database. Each data entry in the store is backed up on one other server in the cluster. This type of store is meant for additive batch writing of write only data. Because this type of store is not meant for reading, updating or deleting data, it does not need to keep a cache. Because this store is meant only for adding data, read performance is poor. However, it is optimized for add operations by performing database writes in batches. |
Each communication service has its own store definition in the directory
domain_home/config/store_schema.
Where domain_home is the directory in which the domain resides, located in Middleware_home/user_projects/domains by default.
The store definitions are JAR files with a configuration file and class definitions for the stored data.
You can specify additional optional attributes for column value definition within the XML configuration file's declarative definition, primarily wlng-cachestore-config-extensions.xml files. You can use this capability when you have some database backend configured for cache persistence. These capabilities add restrictions on database table structures to improve consistency and integrity and to prevent erroneous code from creating or inserting data when it should be prohibited by business logic.
Storage layer configuration includes the following capabilities:
Ability to specify some non-key database fields or columns as not-null
The NOT NULL constraint enforces a column to not accept NULL values
Ability to specify the default value for some non-key database fields or columns
Ability to specify a unique constraint clause for some database fields or columns
Both UNIQUE and PRIMARY KEY constraints provide a guarantee of uniqueness for a column or set of columns
The following elements in the XSD file wlng-cachestore-config.xsd correspond to the declarative definitions in the form of wlng-cachestore-config-extensions.xml files:
<xs:element name="value_column">
<xs:complexType>
<xs:sequence>
<xs:element ref="wlng:methods" />
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required" />
<xs:attribute name="data_type" type="xs:string" use="required" />
<xs:attribute name="desc" type="xs:string" use="optional" />
<xs:attribute name="notnull" type="xs:boolean" default="false" use="optional" />
<xs:attribute name="default" type="xs:string" use="optional" />
</xs:complexType>
</xs:element>
As an example, the bea/prm2/nt/store/wlng-cachestore-config-extensions.xml file implements the following field definitions:
The prm2_partner_profile_data database table makes the email field not null
The prm2_partner_profile_data database table assigns the phoneNumber field a default value of 123.
<db_table name="prm2_partner_profile_data"
desc="This table is maintained by interface SLAImplBean of Portal NT service. The record will be inserted by method , and deleted by method .">
<key_column name="userName" data_type="VARCHAR(100)"
desc="User name of partner." />
...
<value_column name="email" data_type="VARCHAR(100)"
desc="The email address of partner." notnull="true">
<methods>
<get_method name="getEmail" />
<set_method name="setEmail" />
</methods>
</value_column>
<value_column name="phoneNumber" data_type="VARCHAR(100)"
desc="The phone number of partner." default="123">
<methods>
<get_method name="getPhoneNumber" />
<set_method name="setPhoneNumber" />
</methods>
</value_column>
The following example shows the resulting output from the database:
[oracle12c@bejsblar01s08 ~]$ sqlplus /nolog
SQL*Plus: Release 12.1.0.1.0 Production on Mon Jun 26 20:37:48 2017
Copyright (c) 1982, 2013, Oracle. All rights reserved.
SQL> conn sys@orcl as sysdba
Enter password:
Connected.
SQL> alter session set container = dev2pdb;
Session altered.
SQL> show con_name
CON_NAME
------------------------------
DEV2PDB
SQL> desc OCSG25LAB.PRM2_PARTNER_PROFILE_DATA;
Name Null? Type
----------------------------------------- -------- ----------------------------
...
COMPANY VARCHAR2(200) STATE VARCHAR2(200) REFERENCEACCOUNT VARCHAR2(100) EMAIL NOT NULL VARCHAR2(100)
...
SQL> Select TABLE_NAME, COLUMN_NAME, DATA_DEFAULT from DBA_TAB_COLUMNS where TABLE_NAME like 'PRM2_PARTNER_PROFILE_DATA' and COLUMN_NAME='PHONENUMBER';TABLE_NAME--------------------------------------------------------------------------------COLUMN_NAME--------------------------------------------------------------------------------DATA_DEFAULT--------------------------------------------------------------------------------PRM2_PARTNER_PROFILE_DATA
PHONENUMBER
123
As another example, the bea/prm2/store/wlng-cachestore-config-extensions.xml file implements the following two unique constraints:
unique constraint for status and userType fields
unique constraint for status and userName fields
<db_table name="prm2_partner_profile_data"
...
<unique_constraint name="u1">
<unique_constraint_column name="status"/>
<unique_constraint_column name="userType"/>
</unique_constraint>
<unique_constraint name="u2">
<unique_constraint_column name="status"/>
<unique_constraint_column name="userName"/>
</unique_constraint>
</db_table>
The following example shows the output from the database:
SQL> SELECT SUBSTR(cc.CONSTRAINT_NAME,1,20) as CONSTRAINT_NAME, SUBSTR(COLUMN_NAME,1,20) as COLUMN_NAME, 2 POSITION 3 FROM all_constraints c 4 JOIN all_cons_columns cc ON (c.owner = cc.owner 5 AND c.constraint_name = cc.constraint_name) 6 WHERE c.constraint_type = 'U' 7 AND c.table_name = 'PRM2_PARTNER_PROFILE_DATA' ORDER BY CONSTRAINT_NAME, POSITION; CONSTRAINT_NAME COLUMN_NAME POSITION -------------------- -------------------- ---------- SYS_C0012380 STATUS 1 SYS_C0012380 USERTYPE 2 SYS_C0012381 STATUS 1 SYS_C0012381 USERNAME 2
To prevent the databases underlying the Storage service from growing too large, you can set an expiration date on Storage service data, after which time the data is deleted. One consequence is that a delivery receipt can be unsuccessful if a message is so old that gets deleted.
You can configure both the data expiration period for a communication service and how often that Services Gatekeeper checks for expired data. See "Configuring the System Wide Expiration Interval" for details on setting system wide expiration limits.
You also have the option of overriding the system wide expiration settings for individual plug-ins or communication services. When the NT servers starts, it probes the system for store expiration settings in this order:
First it probes whether an XML file exists with the same name as a store jar file. If it finds one, it uses any settings in that file. For example, com.bea.wlcp.wlng.cc_interceptor.store_6.0.0.0.xml.
If no XML file is found, the NT server probes for an internal configuration file, and uses any settings in it. See "Overriding the Expiration Interval Using Jar files" for details on using an internal configuration file.
Finally, the NT server probes for an expiration setting in the store.properties file. For details on using the store.properties file, see "Overriding the Expiration Interval Using the store.properties File".
At the system level, Services Gatekeeper checks whether storage data has expired at a set interval defined by the com.bea.wlcp.wlng.storage.expiry_period variable. The default for the expiry_period is 1800000 milliseconds (thirty minutes).
You can configure this value on server startup by passing it as a Java option when you restart Services Gatekeeper. The option is:
JAVA_OPTIONS="${JAVA_OPTIONS} -Dcom.bea.wlcp.wlng.storage.expiry_period=expiry_period_value"
For example, the following flag configures Services Gatekeeper to check for expired data once an hour:
JAVA_OPTIONS="${JAVA_OPTIONS} -Dcom.bea.wlcp.wlng.storage.expiry_period=3600000"
This section explains how to override the system wide expiration interval for an individual plug-in or communication service using the jar file.
Note:
Perform this task whenever the jar file is replaced.To override the system wide expiration interval:
Locate the store schema JAR file for the store that you want to configure.
These jar files are in under the domain_home/config/store_schema directory.
For example, the JAR file for the common SMPP store is domain_home/config/store_schema/com.bea.wlcp.wlng.sms.common.store.
Extract the files from the JAR file for the store that you want to configure.
Open the wlng-cachestore-config-extensions.xml file.
In the extensions file, create or edit the <expiry> element, setting its expiry_age value. The value is in seconds.
Save the file.
If expiry_age is not set, the data never expires.
The following example shows the configuration of the MO message store setting the expiration period to 604800 seconds (one week).
<!-- MO message store (common) start -->
<db_table name="pl_sms_mo_sms">
<key_column name="msg_id" data_type="VARCHAR(30)"/>
<bucket_column name="smsdata" data_type="BLOB"/>
<value_column name="notif_correlator" data_type="VARCHAR(30)">
<methods>
<get_method name="getNotificationInfoCorrelator"/>
<set_method name="setNotificationInfoCorrelator"/>
</methods>
</value_column>
<expiry expiry_age="604800"/> <!-- 1 week -->
</db_table>
This section explains how to override the system wide expiration interval for individual plug-ins or communication services using a store.properties file that you create. The steps that restart the servers ensure that your changes are propagated to your other servers.
These changes are persistent, and need not be repeated if the plug-in jar files are replaced.
To override the system wide expiration interval:
Navigate to domain_home/config/store_schema.
Create a store.properties file using any text editor.
Add an entry to set the expiration interval (in seconds) for a plug-in with this syntax:
table_name.expiry=expiration_interval
For example, this entry sets the SMS Plug-in expiration interval to five minutes:
pl_sms_smpp_mt_sms.expiry=300
Repeat step 3 for all plug-ins or communication services that you are overridign the system expiration interval for.
Save and close store.properties.
Restart the administration server.
(In a multi-tier implementation) Restart the network tier server.
Set field values and use methods from the Administration Console, by selecting Container, then Services, and then StoreageServiceMBean. Alternately, use a Java application. For information on the methods and fields, see the ”All Classes” section of Services Gatekeeper OAM Java API Reference.