This document describes the architecture of the Sh Cache RA, its configuration, and alarms. Additionally a listing of Data References from the Sh protocol is provided.
Overview
The Sh Cache Resource Adaptor contains a Diameter Sh stack which it uses to send requests to the HSS, and a series of caches in which it stores the information received in response. For more information on how to configure the Sh Cache Resource Adaptor see Sh Cache RA configuration. The Sh interface is specified on 3GPP TS 129 328 and 3GPP TS 129 329. The current implementation follows the Release 11.18.
Basic components
![sh cache ra arch](images/sh-cache-architecture/sh-cache-ra-arch.png)
![]() |
Important terms
Here are some key terms used in the diagram.
|
Basic cache function
When a cache client requires a piece of information for a given subscriber, it must ask the RA to provide it with the appropriate cache instance for that type of information. The client then queries the cache directly. If the cache already contains the requested information, it can provide it immediately. If it does not have the information, the cache will request the information from the appropriate HSS. When the data is received from the HSS,the cache will automatically store the information and then provide it back to the original requesting client.
The precise behaviour of a given cache instance is determined by its cache configuration. This configuration determines how and when to use data within the cache and when to request information from the HSS.
Cache instances and types
The Sh Cache RA holds many cache instances. These caches are contained within the JVM heap. Instances are created on demand through an API. At creation each cache is provided with a configuration that defines its caching behaviour.
Each cache instance has a specific type corresponding to the type of data contained within the cache instance. These cache types fall into one of two categories:
-
non-transparent data caches correspond to the non-transparent data fields defined in the Sh protocol where there is a cache type built into the Sh Cache RA for each of the available fields. Each non-transparent cache contains a single value type — this is a Java type that is directly mapped to the Sh protocol description.
-
transparent data cache types are defined by the clients using the Sh Cache RA. Each transparent data cache corresponds to a particular service indication as defined by the client. The appropriate codec and Java type for the cache data must be provided by the client.
Each transparent cache stores the XML document (a DOM element) and is templated on the Java type for this element, as well as the current sequence number for that Document. So transparent data caches are “document caches”.
Transparent data caches require a codec to convert their data between an XML document and its associated Java type. There are many different frameworks available for use of XML within Java. We have chosen JAXB for our Sh Cache RA, and therefore we also chose JAXB for the MMTEL services codec; however, there is nothing to prevent the choice of DOM, Apache JDOM, or any other framework instead of JAXB.
Cache configuration
Clients provide a cache configuration when asking for a cache. Each cache configuration corresponds directly to a cache instance within the RA. The first call to the RA with a given configuration will result in a new cache being created with that configuration. Subsequent calls to the RA with the same configuration will retrieve the already existing instance for that configuration. Clients can ask the RA to provide a default configuration for each non-transparent cache type.
All cache configurations contain the following information:
-
the Diameter destination host and destination realm for the HSS that is to be used by the cache instance (different cache instances may interact with different HSSs)
-
the Cache Retention Strategy, which includes:
-
the basic caching strategy (see Caching strategy)
-
whether or not to subscribe to updates
-
size and time parameters for the basic strategy.
-
Transparent data cache configurations also include:
-
the Service Indication of the transparent data.
Management interface
The Sh Cache RA provides an interface for management operations. These can be divided into invalidation and counting operations.
Invalidation operations
These act on all Sh Cache RAs within the rhino cluster
-
drop all caches
-
drop all transparent data caches
-
drop all transparent data caches of a specific service indication
-
drop all caches of a specified Data Reference
-
invalidate all transparent data cache entries of a specified subscriber
-
invalidate all cache entries matching an access key
More information on the invalidation operations can be found in Cache invalidation.
Counting operations
These return cache and cache entry counts for the rhino node they were invoked on
-
count all caches on
-
count all transparent data caches
-
count all transparent data caches of a specified service indication
-
count all caches of a specified data reference
-
count all transparent data cache entries for a specified subscriber
-
count all cache entries matching an access key
Diameter and Diameter Sh use
The Sh Cache RA embeds the OpenCloud Diameter Stack, and the Sh Protocol API. None of the Sh protocol “efficiency” features are used by the RA. When a client asks the Sh Cache RA for some data, the RA will check the cache for the data; if the data is not present, the RA will perform a single Sh query to the HSS for the data. The Sh Cache RA will not ask the HSS for multiple items within the same Sh request.
Diameter Peer and peer configuration in the Sh Cache RA works in the same way as other OpenCloud Diameter RAs.
Therefore, an entity of the Sh Cache RA can connect to multiple discrete HSS.
Synchronous and asynchronous lookups
The Sh Cache RA supports both synchronous and asynchronous methods of retrieving and updating information in the HSS:
-
Synchronous methods simply block the caller until the information retrieval/update is complete. This means that if the request requires communication with the HSS, the client is forced to wait until the Sh transaction is complete before doing anything else.
-
Asynchronous methods are non-blocking for retrieving and updating information. They use SLEE events to alert the client when their transaction is complete.
Cache invalidation
Data stored within a Cache resides in the Heap (main memory) of a Rhino cluster node. If the original data has changed, it is necessary to remove any cached copies so that the next time the data is read the new value is used.
A common scenario for cache invalidation is where a user’s data is stored in Transparent Data in the HSS, and cached for session processing. It is cached for session processing to speed up session processing and offload the HSS. The user then updates their data, and expects that the next session they participate in reflects their new settings (for example, anonymity or barring of outgoing international calls).
Invalidation Management API
The Cache can be invalidated through a management API (called an invalidation API). This exists to be integrated into other systems such as:
-
an operator’s provisioning system
-
an XCAP server
The invalidation API is "cluster-wide". I.e. even though there can be many Rhino cluster members, any single member can receive the invocation and is then responsible for invalidating all copies of the cached data across the cluster.
Javadoc for this API is available in Sh Cache Management API.
Conditions to invalidate Caches and their Entries
All caches are dropped when:
-
a Rhino cluster restarts
-
the Invalidation Management API is invoked to invalidate all caches
Specific cache entries are invalidated when:
-
an invalidation operation is triggered on the management interface
-
on receiving a PNR message with empty service data
-
on receiving a cache invalidation message from another node
Cache invalidation messages
An Sh Cache RA can broadcast cache invalidation messages to other Rhino cluster members to trigger invalidation of specific cache entries.
These messages are sent when a Push Notification Request is received from the HSS, and the invalidation management API is invoked.
![sh cache ra architecture message invalidation](images/sh-cache-architecture/sh-cache-ra-architecture-message-invalidation.png)
The invalidation messages can be turned on or off by DataReference when acting on PNR messages. See DataReference cache configuration for more information.
Sh Cache RA configuration
DataReference cache configuration
The feature or SBB creating a cache ultimately decides its configuration; but it can choose from a series of default cache configurations that the Sh Cache RA provides. These include configurations for each of the possible non-transparent data fields, plus a default configuration for transparent data (listed as “Repository Data”). The configurations are stored in a profile table with the name: ShCacheDataReferenceConfigTable
.
Each Data Reference may have zero or more Cache’s in the Sh Cache RA.
These following table provides the attributes and their definition.
Attribute name | Description |
---|---|
Data Reference name (profile name) |
Identifies what data is stored in the cache. The supported values are: REPOSITORY_DATA, IMS_PUBLIC_IDENTITY, IMS_USER_STATE, S_CSCFNAME, INITIAL_FILTER_CRITERIA, PS_LOCATION_INFORMATION, CS_LOCATION_INFORMATION, PS_USER_STATE, CS_USER_STATE, CHARGING_INFORMATION, MSISDN, PSIACTIVATION, DSAI, SERVICE_LEVEL_TRACE_INFO, IP_ADDRESS_SECURE_BINDING_INFORMATION, SERVICE_PRIORITY_LEVEL, SMS_REGISTRATION_INFO, UE_REACHABILITY_FOR_IP, TADS_INFORMATION,STN_SR, UE_SRVCC_CAPABILITY, EXTENDED_PRIORITY, CSRN, REFERENCE_LOCATION_INFORMATION. See Sh DataReference for more information. |
CacheTypeStrategy |
Determines the behaviour of the cache. The possible values are: |
CacheEvictionStrategy |
Determines how the cache is evicted. Possible values are: |
CacheStrategy |
Deprecated. Present for backwards compatibility. Use |
CacheRetentionMaxEntries |
Determines the maximum number of entries allowed in the cache. |
CacheRetentionTimeoutMillis |
Determines the timeout period (in milliseconds) used by certain cache strategies. It will evict a cache entry after this value when the |
CacheWriteTimeoutMillis |
Determines the timeout period (in milliseconds) used by certain cache strategies. It will evict a cache entry after this value when the |
CacheFirePushNotification |
If set to true the Sh Cache Resource Adaptor Entity will fire a SLEE event on receipt of an Sh Push Notification Request. |
OneTimeNotification |
Indicates to the HSS to send just one Push Notification Request (PNR) for a subscribed cache. When the |
SendDataIndicatorAllowedInSNR |
Indicates to the HSS to include the stored Data for a Data Reference on a response to a Subscribe-Notifications-Request message (SNR). |
InvalidationMessageActive |
When set to true, a cluster-wide invalidation protocol is enabled on receipt of a PNR message. For further information please see Cache invalidation. |
Caching strategy
The caching retention strategy has two major effects on a cache’s behaviour:
-
It determines how and when an entry in the cache should be marked as invalid and no longer visible to applications using the Resource Adaptor
-
It determines whether the cache should request the HSS to send notifications of data being changed in the HSS
The caching strategies is divided in two sets of parameters: CacheTypeStrategy
and CacheEvictionStrategy
.
Cache Type Strategy
Value | Description |
---|---|
NoCache |
The cache functionality will not be used; every read and write will always query the HSS for the requested information. Subscription is not applicable. |
SimpleCache |
Results from HSS queries will be cached. Updates will always write through to the HSS. The cache will not receive updates from the HSS. |
SubscriptionCache |
Results from HSS queries will be cached. Updates will always write through to the HSS. Cache entries will be updated if the data is changed in the HSS. |
Cache Eviction Strategy
Value | Description |
---|---|
AccessTime |
Cache entries will be evicted when the time (in milliseconds) since they were last updated or read exceeds the value of |
WriteTime |
Cache entries will be evicted when the time (in milliseconds) since they were last updated exceeds the value of |
CacheSize |
Cache entries will begin to be evicted when the number of cache entries comes within approximately 20% of the |
NoEviction |
It is equivalent of |
Diameter configuration
The Diameter configuration for the Sh Cache RA works in a similar way to other OpenCloud Diameter RAs. The configuration data is stored in two places: most of it is in the ShCacheDiameterConfiguration
profile table; the rest is in the properties of the Sh Cache RA. For more information see Configuring Diameter Resource Adaptors.
Sh Cache RA properties
Property Name | Description | Default Values |
---|---|---|
DestinationHost |
A default destination host that is used when a cache config is created without an explicit destination host. |
ShHSS |
DestinationRealm |
A default destination realm that is used when a cache config is created without an explicit destination realm. |
example |
ConfigurationProfile |
The name of the profile table and profile where the RA’s Diameter configuration is stored. Has the format: |
ShCacheDiameterConfiguration/client |
ConnectTimeout |
Timeout in milliseconds for waiting for outgoing transport connection establishment |
30000 |
RequestTimeout |
Timeout in milliseconds for waiting for responses before firing a Timeout event |
30000 |
ReconnectDelay |
Delay in milliseconds before reconnecting (RFC6733 timer Tc) |
30000 |
WatchdogTimeout |
Timeout in milliseconds for waiting for watchdog responses (RFC3539 timer Tw) |
30000 |
ForceReconnectAfterDPR |
if true, always attempt to reconnect even if the server sent a DPR with Disconnect-Cause set to DO_NOT_WANT_TO_TALK_TO_YOU |
false |
ThreadPoolSize |
Size of thread pool for decoding incoming diameter messages |
0 |
WorkQueueSize |
Size of the task queue of thread pool for decoding incoming diameter messages |
0 |
IOServerWorkers |
Number of IO threads serving incoming connections |
0 |
IOClientWorkers |
Number of IO threads serving outgoing connections |
0 |
ConfigurationProfilePollTime |
Time in milliseconds between polling for changes to ConfigurationProfile, in milliseconds. Values |
40000 |
ShCacheDiameterConfiguration fields
Field Name | Description | Default Value |
---|---|---|
ProductVendorID |
Vendor ID; must be |
19808 |
ApplicationVendorID |
Diameter Application ID. |
0 |
Host |
Host to use in all Origin-Host AVPs; must be resolvable. |
diameterclient |
Realm |
Realm to use in all Origin-Realm AVPs. |
example |
Peer Table |
A valid XML document for peer table configuration. |
|
Realm Table |
A valid XML document for realm table configuration. |
|
Product |
Product name to use in Product-Name AVPs generated by the stack. |
OpenCloud Diameter |
Version |
Version number to use in all Firmware-Revision AVPs generated by the stack; must be a positive integer. |
1 |
![]() |
For details of the XML structure of the peer and realm tables, see Configuring Peer and Realm Tables. |
Data Reference default configuration
The following table shows the default configurations available in the Sh Cache RA:
Data Reference | CacheTypeStrategy | CacheEvictionStrategy | CacheRetentionMaxEntries | CacheRetentionTimeoutMillis | CacheWriteTimeoutMillis | CacheFirePushNotification | OneTimeNotification | SendDataIndicatorAllowedInSNR | InvalidationMessageActive |
---|---|---|---|---|---|---|---|---|---|
REPOSITORY_DATA |
SimpleCache |
WriteTime |
100000 |
30000 |
30000 |
true |
false |
true |
true |
IMS_PUBLIC_IDENTITY |
SimpleCache |
WriteTime |
100000 |
30000 |
30000 |
true |
false |
true |
false |
IMS_USER_STATE |
NoCache |
NoEviction |
100000 |
3600000 |
3600000 |
true |
false |
true |
false |
S_CSCFNAME |
SimpleCache |
WriteTime |
100000 |
30000 |
30000 |
true |
false |
true |
false |
INITIAL_FILTER_CRITERIA |
NoCache |
NoEviction |
100000 |
3600000 |
3600000 |
true |
false |
true |
false |
PS_LOCATION_INFORMATION |
NoCache |
NoEviction |
100000 |
20000 |
20000 |
true |
false |
true |
false |
CS_LOCATION_INFORMATION |
NoCache |
NoEviction |
100000 |
20000 |
20000 |
true |
false |
true |
false |
PS_USER_STATE |
NoCache |
NoEviction |
100000 |
3600000 |
3600000 |
true |
false |
true |
false |
CS_USER_STATE |
NoCache |
NoEviction |
100000 |
3600000 |
3600000 |
true |
false |
true |
false |
CHARGING_INFORMATION |
SimpleCache |
WriteTime |
100000 |
30000 |
30000 |
true |
false |
true |
false |
MSISDN |
SimpleCache |
WriteTime |
100000 |
30000 |
30000 |
true |
false |
true |
false |
PSIACTIVATION |
NoCache |
NoEviction |
100000 |
3600000 |
3600000 |
true |
false |
true |
false |
DSAI |
NoCache |
NoEviction |
100000 |
3600000 |
3600000 |
true |
false |
true |
false |
SERVICE_LEVEL_TRACE_INFO |
NoCache |
NoEviction |
100000 |
3600000 |
3600000 |
true |
false |
true |
false |
SERVICE_PRIORITY_LEVEL |
NoCache |
NoEviction |
100000 |
3600000 |
3600000 |
true |
false |
true |
false |
SMS_REGISTRATION_INFO |
NoCache |
NoEviction |
100000 |
3600000 |
3600000 |
true |
false |
true |
false |
UE_REACHABILITY_FOR_IP |
NoCache |
NoEviction |
100000 |
3600000 |
3600000 |
false |
true |
false |
false |
TADS_INFORMATION |
NoCache |
NoEviction |
100000 |
3600000 |
3600000 |
true |
false |
true |
false |
STN_SR |
SimpleCache |
WriteTime |
100000 |
3600000 |
3600000 |
true |
false |
true |
false |
UE_SRVCC_CAPABILITY |
SimpleCache |
WriteTime |
100000 |
3600000 |
3600000 |
true |
false |
true |
false |
EXTENDED_PRIORITY |
NoCache |
NoEviction |
100000 |
3600000 |
3600000 |
true |
false |
true |
false |
CSRN |
NoCache |
NoEviction |
100000 |
3600000 |
3600000 |
true |
false |
true |
false |
REFERENCE_LOCATION_INFORMATION |
NoCache |
NoEviction |
100000 |
20000 |
20000 |
true |
false |
true |
false |
IP_ADDRESS_SECURE_BINDING_INFORMATION |
NoCache |
NoEviction |
100000 |
3600000 |
3600000 |
true |
false |
true |
false |
Alarms
The Sh Cache RA defines the following alarms.
Alarm | Level | Raised when … | Clear condition |
---|---|---|---|
ShCache.SubscriberNotificationsAnswerExpiry |
WARNING |
the SNA responds with less time than the amount of time requested |
Cleared manually |
ShDataRefCacheConfig.MissingProfile |
MAJOR |
an attempt to read a data reference cache default configuration profile fails because the profile was not present |
On the next successful attempt to read the profile |
ShDataRefCacheConfig.MissingProfileTable |
MAJOR |
an attempt to read a data reference cache default configuration profile fails because the profile table was not present |
On the next successful attempt to access the profile table |
ShDataRefCacheConfig.BadProfileSpecification |
MAJOR |
an attempt to read a data reference cache default configuration profile fails because the profile uses an unexpected specification |
On the next attempt to read the profile once it has the correct specification |
ShDataRefCacheConfig.TransactionFailure |
MAJOR |
an attempt to read a data from a profile table fails |
On the next successful attempt to read the profile table |
active-reconfiguration |
WARNING |
a fixed configuration property (such as the host or realm) is changed while the RA entity is active |
When the RA entity is deactivated |
Sh DataReference
The Data References for the Sh protocol are defined in the 3GPP TS 29.328 specification. The version of the specification in use is described in the Sh Cache Resource Adaptor Statement of Compliance
Each Data Reference defines a set of information stored in the HSS as well as the "key" to accessing it (called the Access key). Each Data Reference type has different Access Key definitions. These can be viewed in Table 7.6.1 of 29.328.
The Data Reference types and the access keys are:
Data reference | Access key |
---|---|
RepositoryData |
Data Reference + ( IMS Public User Identity OR Public Service Identity ) + Service Indication |
IMSPublicIdentity |
Data Reference + ( IMS Public User Identity OR Public Service Identity OR MSISDN ) + [ Requested Identity Set ] |
IMSUserState |
Data Reference + IMS Public User Identity |
S-CSCFName |
Data Reference + ( IMS Public User Identity OR Public Service Identity ) |
InitialFilterCriteria |
Data Reference + ( IMS Public User Identity OR Public Service Identity ) + Application Server Name |
LocationInformation |
Data Reference + ( IMS Public User Identity OR MSISDN ) + [ Private Identity ] + Requested Domain + Current Location + [ Serving Node Indication ] + [ Requested Nodes ] + [ Local Time Zone Indication ] |
UserState |
Data Reference + ( IMS Public User Identity OR MSISDN ) + [ Private Identity ] + Requested Domain + [ Requested Nodes ] |
Charging information |
Data Reference + ( IMS Public User Identity OR Public Service Identity OR MSISDN ) |
MSISDN or MSISDN + ExtendedMSISDN |
Data Reference + ( IMS Public User Identity OR MSISDN ) + [ Private Identity ] |
PSIActivation |
Data Reference + IMS Public Service Identity |
DSAI |
Data Reference + ( IMS Public User Identity OR Public Service Identity ) + DSAI Tag + Application Server Name |
ServiceLevelTraceInfo |
Data Reference + ( IMS Public User Identity OR MSISDN ) |
IP Address Secure Binding Information |
Data Reference + ( IMS Public User Identity ) |
Service Priority Level |
Data Reference + ( IMS Public User Identity ) |
SMSRegistrationInfo |
Data Reference + ( IMS Public User Identity OR MSISDN ) + [ Private Identity ] |
UE reachability for IP |
Data Reference + ( IMS Public User Identity OR MSISDN ) + [ Private Identity ] |
T-ADS Information |
Data Reference + ( IMS Public User Identity OR MSISDN ) + [ Private Identity ] |
STN-SR |
Data Reference + ( IMS Public User Identity OR MSISDN ) + [ Private Identity ] |
UE-SRVCC- Capability |
Data Reference + ( IMS Public User Identity OR MSISDN ) + [ Private Identity ] |
ExtendedPriority |
Data Reference + ( IMS Public User Identity OR MSISDN ) + [ Private Identity ] |
CSRN |
Data Reference + ( IMS Public User Identity OR MSISDN ) + [ Private Identity ] |
Reference Location Information |
Data Reference + ( IMS Public User Identity ) + [ Private Identity ] |
![]() |
When querying the HSS for MSISDN data, VoLTE by default sets the identity type to IMPU. When using the Sh Cache Rest Api to act on the MSISDN caches, set the identity type to IMPU |
Each Data Reference corresponds to logically distinct information in the HSS. The act of placing a Data Reference (and associated access key information) into a read Request to the HSS instructs the HSS to read the appropriate information and return it. A rough analogy is that a Data Reference might be considered a Database Table, and the Access Key the requested row in the table.
Some Data References allow the Application Server to read and write data stored in the HSS (for example Repository Data). Others allow read only (for example T-ADS information). For further details please refer to table 7.6.1 of 29.328.