Overview
|
In cases where a Web Service is serving the same request (and generating
the same response) over and over again, it makes sense to use a caching
mechanism. When a cache is employed, a unique identifier for the request
is cached together with the corresponding response for this request. If
an identical request is received, the response can be retrieved from
the cache instead of forcing the Web Service to reprocess the identical
request and generate the same response. The use of caching in this way
helps divert unnecessary traffic from the Web Service and makes it more
responsive to new requests.
For example, assume you have deployed a Web Service that returns a list
of cities in the USA from an external database, which is then used
by a variety of Web-based applications. Because the names and quantity
of cities in the USA are relatively constant, if the Web Service is
handling hundreds or thousands of requests every day, this represents
a serious waste of processing time and effort, especially considering
that the database that contains the relatively fixed list of city names
is hosted on a separate machine to the service.
If you assume that the list of cities in the database does not change very
often, it makes sense to use Oracle Enterprise Gateway to cache the response
from the Web Service that contains the list of cities. Then when a request
for this Web Service is identified by the Enterprise Gateway, the cached response
can be returned to the client. This approach results in the following
performance improvements:
-
The Enterprise Gateway does not have to route the message on to the Web
Service, therefore saving the processing effort required, and perhaps
more importantly, saving the time it takes for the round trip.
-
The Web Service does not have to waste processing power on
generating the same list over and over again, therefore making it
more responsive to requests for other services.
-
Assuming a naive implementation of database retrieval and caching,
the Web Service does not have to query the database (over the
network) and collate the results over and over again for every
request.
The caching mechanism used in the Enterprise Gateway offers full control over
the size of the cache, the lifetime of objects in the cache, whether
objects are cached to disk or not, and even whether caches can be
replicated across multiple instances of Enterprise Gateways. The following
sections describe how to configure both local and distributed caches
in the Enterprise Gateway, concluding with a detailed example of how to
configure a circuit to cache responses.
|
Local Caches
|
Local caches are used where a single Enterprise Gateway instance has been
deployed. In such cases, you do not need to replicate caches
across multiple running instances of the Enterprise Gateway.
In the Policy Studio, you can add a local cache, by selecting the top-level
Caches tree item on the External Connections tab,
and clicking the Add button at the bottom right of the screen.
Select Add Local Cache from the menu. You can configure the
following fields on the Configure Local Cache dialog:
Cache Name:
Enter a name for the cache.
Maximum Elements in Memory:
Enter the maximum number of objects that can be in memory at any one time.
Maximum Elements on Disk:
Sets the maximum number of objects that can be stored in the disk store
at any one time. A value of zero indicates an unlimited number of objects.
Eternal:
If this option is selected, objects stored in the caches never expire
and timeouts have no effect.
Overflow to Disk:
Select this option if you want the cache to overflow to disk when the
number of objects in memory has reached the amount set in the
Maximum Elements in Memory field above.
Note:
The following fields are optional:
Time to Idle:
Determines the maximum amount of time (in seconds) between accesses that
an object can remain idle before it expires. A value of zero indicates
that objects can idle for infinity, which is the default value. Note that
if the Eternal field is selected, this setting is ignored.
Time to Live:
Sets the maximum time between when an object is created and when it
expires. The default value is zero, which means that the object can live
for infinity. Note that if the Eternal field is
selected, this setting is ignored.
Persist to Disk:
If selected, the disk store is persisted between JVM restarts.
This option is disabled by default.
Disk Expiry Interval:
Configures the number of seconds between runs of the disk
expiry thread. The default is 120 seconds.
Disk Spool Buffer Size:
Indicates the size of memory (in MBs) to allocate the disk store for a spool
buffer. Writes are made to this memory and then asynchronously written to disk.
The default size is 30 MB. If you get OutOfMemory exceptions,
you may consider lowering this value. However, if you notice poor performance,
you should increase the value.
Eviction Policy:
Select the eviction policy that the cache uses to evict objects from
the cache. The default policy is Least Recently Used.
However, you can also use First in First Out and
Less Frequently Used.
|
Distributed Caches
|
If you have deployed several Enterprise Gateways throughout your network, you
need to employ a distributed cache. In this scenario, each Enterprise Gateway
has its own local copy of the cache but registers a cache event listener
that replicates messages to the other caches so that put, remove, expiry,
and delete events on a single cache are duplicated across all other caches.
You can configure a distributed cache by selecting the top-level
Caches tree item on the External Connections tab,
and clicking the Add button at the bottom right of the screen.
Select Add Distributed Cache from the menu, and configure the
following fields on the Configure Distributed Cache dialog:
Note:
Many of the settings for the distributed cache are identical to those for
the local cache. For details on how to configure these fields, see the
Local Caches section. The
following information refers to fields that are not displayed on both
dialogs.
Event Listener Class Name:
Enter the name of the listener factory class that enables this cache
to register listeners for cache events, such as put, remove, delete,
and expire.
Properties Separator:
Specify the character to use to separate the list of properties.
Properties:
Specify the properties to pass to the RMICacheReplicatorFactory .
The following properties are available:
-
replicatePuts=true | false
Determines whether new elements placed in a cache are replicated to
other caches. Default is true .
-
replicateUpdates=true | false
Determines whether new elements that override (update) existing
elements with the same key in a cache are replicated. Default is
true .
-
replicateRemovals=true
Determines whether element removals are replicated. Default is
true .
-
replicateAsynchronously=true | false
Determines whether replications are asynchronous (true) or
synchronous (false). Default is false .
-
replicateUpdatesViaCopy=true | false
Determines whether new elements are copied to other caches (true)
or a remove message is sent (false). Default is true .
-
asynchronousReplicationIntervalMillis=[number of ms]
The asynchronous replicator runs at a set interval of milliseconds.
The default is 1000 and the minimum is 10. This property is only
applicable if replicateAsynchronously=true .
Cache Bootstrap Class Name:
Specifies a BootstrapCacheLoader factory that the cache can call
on initialization to pre-populate itself. The RMIBootstrapCacheLoader
bootstraps caches in clusters where RMICacheReplicator s are used.
Properties Separator:
The character entered here is used to separate the list of properties
listed in the field below.
Properties:
The properties listed here are used to initialize the
RMIBootstrapCacheLoaderFactory . The following properties are recognized:
-
bootstrapAsynchronously=true | false
Determines whether the bootstrap happens in the background after the
cache has started (true), or if bootstrapping must complete before the
cache is made available (false). Default is true .
-
maximumChunkSizeBytes=[integer]
Caches can potentially grow larger than the memory limits on the JVM.
This property enables the bootstrapper to fetch elements in chunks.
The default chunk size is 5000000 (5 MB).
|
Cache Settings
|
In a distributed cache, there is no master cache controlling all caches
in the group. Instead, each cache is a peer in the group and needs
to know where all the other peers in the group are located.
Peer Discovery and Peer Listeners
are two essential parts of any distributed cache system.
You can configure these by right-clicking the top-level Caches
tree item on the External Connections tab, and selecting
Edit Cache Settings. Configure the following fields on the
Cache Settings dialog:
Peer Provider Class:
By default, the built-in peer discovery class factory is used:
net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory
Properties Separator:
Specify the token used as the separator for the list of properties in the
next field.
Properties:
The properties listed here specify whether the peer discovery mechanism
is automatic or manual. If the automatic mechanism is used, each peer
uses TCP multicast to establish and maintain a multicast group. This is
the default option because it requires minimal configuration and peers
can be automatically added and removed from the group. Each peer pings
the group every second. If a peer has not pinged any of the other peers
after 5 seconds, it is dropped from the group, while a new peer is admitted
to the group if it starts pinging the other peers.
To use automatic peer discovery, ensure that the peerDiscovery
setting is set to automatic . You can specify the multicast
address and port using the multicastGroupAddress and
multicastGroupPort settings. You can specify the time to
live for multicast datagrams using the timeToLive setting.
Alternatively, you can configure a manual peer discovery mechanism,
whereby each peer definitively lists the peers that it wants to
communicate with. This should only be used in networks where there
are problems propagating multicast datagrams. To use a manual
peer discovery mechanism, make sure the peerDiscovery
setting is set to manual . The list of RMI URLs
of the other peers in the group must also be specified, for example:
rmiUrls=//server2:40001/sampleCache1|//server2:40001/sampleCache2
.
Peer Listener Class:
The peer listener class specified is responsible for listening for
messages from peers in the group.
Properties Separator:
Specify the token used to separate the list of properties.
Properties:
The properties entered configure the way the listener behaves.
Valid properties are as follows:
hostname (optional)
Hostname of the machine on which the listener is listening.
Note that, by default, this is set to localhost ,
which maps to the local loopback address of 127.0.0.1 ,
which is not addressable from another machine on the network.
If you intend this cache to be used over the network, you should
change this address to the IP address of the network interface
on which the listener is listening.
port (mandatory)
Specify the port on which the listener is listening, which by default
is 4001. This setting is mandatory.
socketTimeoutMillis (optional)
Enter the number of seconds that client sockets wait when sending
messages to this listener until they give up. The default is 2000 ms.
Notify replicators of removal of items during refresh:
A server refresh automatically purges all items from the cache (for example,
when configuration updates are deployed to the Enterprise Gateway). If this checkbox
is selected, the contents of each peer in the group are also purged.
This avoids a situation where a single peer is refreshed (and has its contents
purged), but the other peers in the group are not purged. If this option is
not selected, the refreshed peer attempts to bootstrap itself to the other peers
in the group, resulting in the cache items becoming replicated in the refreshed cache.
This effectively negates the effect of the server refresh and may result in
inconsistent behavior.
|
Example of Caching Response Messages
|
This simple example shows how to construct a circuit that caches responses from
the Web Service. It uses the request body to identify identical successive requests.
In other words, if the Enterprise Gateway receives two successive requests with an identical
message body, it returns the corresponding response from the cache instead of routing
the request to the Web Service.
The following diagram illustrates the complete circuit:
Caching Response Messages
|
The logic of the circuit is summarized as follows:
-
The purpose of the first filter is to configure what part of the
request you want to use to identify unique requests. This example
uses the request body as the unique key, which is then used to
look up the appropriate response message from the cache.
-
The second filter looks up the request body in the response cache to
see if it contains the request body. If it does, the response
message that corresponds to this request is returned to the client.
-
If it does not, the request is routed to the Web Service, which
processes it (by connecting to a database over the network and
running a SQL statement) and returns a response to the Enterprise Gateway.
-
The Enterprise Gateway then returns the response to the client and
caches it in the response cache.
-
When the next identical request is received by the Enterprise Gateway,
the corresponding response is located in the responses cache
and returned immediately to the client.
You must configure the following caching filters to achieve this circuit.
For convenience, the routing filters will not be included because the
configuration options depend on your target Web Service.
Create Key Filter:
This filter is used to decide what part of the request is used in order
for a request to be considered unique. Different parts of the request
can be identified internally using Oracle message attributes, for
example, content.body contains the request body. The
following fields must be configured for this filter:
-
Name: Use request body to create unique key
-
Attribute Name: content.body
Is Cached?:
This filter looks up the cache to see if a response has been stored
for the current request. It looks up the cache using a message
attribute, which is message.key by default. The
message.key attribute contains a hash of the request
message, and can be used as the key for objects in the cache. If the
key is found in the cache, the value of the key (cached response
for this request) is written to the content.body
attribute, which can be returned to the client using the
Reflect filter. You must configure the following
fields:
-
Name: Is a response for this request already cached?
-
Cache containing key: Response Cache (assuming
you have created a cache of this name)
-
Attribute Containing Key:
message.key
-
Overwrite attribute name if found:
content.body
Reflect:
If the Is Cached? filter passes, it retrieves the
response from the cache and stores it in the content.body
message attribute. The Reflect filter is used to return
the cached response to the client.
Routing:
If a response for this request could not be located in the cache, the
Enterprise Gateway routes the request to the Web Service, and waits for a
response. For more details on how to route messages, see the
Routing Configuration
tutorial.
Cache Attribute:
When the response has been received from the Web Service, it should be
cached for future use. The Cache Attribute filter
is used to configure the key used to look up the cache and which aspect
of the response message is stored as the key value in the cache. Note
that this example specifies the value of the content.body
attribute to cache. Because this filter is configured after
the routing filters, this attribute contains the response message. Note
also that the value entered in the Attribute Key field
should match that entered in the Attribute containing key
field in the Is Cached? filter. You must configure the
following fields:
-
Name: Cache response body
-
Cache to use: Response Cache
-
Attribute key:
message.key
-
Attribute name to store:
content.body
For more information on these filters, see the following topics:
|
|