使用 DistributedMap and DistributedObjectCache 接口进行动态高速缓存

通过使用 DistributedMap 或 DistributedObjectCache 接口， Java™ Platform, Enterprise Edition ( Java EE ) 应用程序和系统组件可以通过在缓存中存储对象引用来缓存和共享 Java 对象。

有关此任务

DistributedMap 和 DistributedObjectCache 接口是简单的动态高速缓存接口。通过使用这些接口， Java EE 应用程序和系统组件可以通过在高速缓存中存储对对象的引用来高速缓存和共享 Java 对象。如果在管理控制台中启用了动态高速缓存服务，那么将创建缺省的动态高速缓存实例。此缺省实例使用名称服务 /cache/distributedmap 绑定到全局 Java 命名和目录接口 (JNDI) 名称空间。

在同一 Java 虚拟机（JVM）上有多个 DistributedMap 和 DistributedObjectCache 接口实例，应用程序可根据需要分别配置缓存实例。 DistributedMap 接口的每个实例都有自己的属性。

小贴士有关 DistributedMap 和 DistributedObjectCache 接口的更多信息，请参阅 com.ibm.websphere.cache 软件包的 API 文档。

重要信息: 如果您正在使用定制对象键，那么必须将类放在共享库中。可以在单元级、节点级或服务器级定义共享库。然后，在每个服务器中，创建类装入器并使其与定义的共享库相关联。有关更多信息，请参阅管理共享库和类装入器设置。

在启用复制的情况下在集群中部署应用程序时，将 JAR 文件放入共享库中。只需开启复制就不需要共享库; 但是，如果您正在使用特定于应用程序的 Java 对象 (例如高速缓存键或高速缓存值) ，那么这些 Java 类必须位于共享库中。如果那些值不在共享库中，那么在数据复制服务 (DRS) 尝试对接收端的那些对象进行反序列化时，将抛出 ClassNotFound 异常。

在集群环境中，您放入高速缓存的内容可以与集群中的其他服务器共享。该内容也可能卸装至磁盘。如果计划让高速缓存的对象共享或卸装至磁盘，那么必须使这些特定对象可序列化。如果您放置在高速缓存中的对象是不可序列化的，那么必须指定这些对象的共享策略为“不共享”。 DistributedMap 接口 DistributedMap 接口包含有关如何指定高速缓存对象的共享策略的信息。对不可序列化的对象指定“不共享”以外的共享策略可能导致系统性能下降。

有四种方法来配置并使用高速缓存实例：

配置缺省对象高速缓存（过程中的方法一）
创建并配置定制对象高速缓存（过程中的方法三）
通过使用 cacheinstances.properties 文件来创建并配置定制对象高速缓存（过程中的方法四）
使用资源引用（过程中的方法五）

过程

方法 1 - 配置缺省高速缓存实例。

如果已启用服务器高速缓存，那么服务器启动时，将创建缺省的 Servlet 高速缓存实例（JNDI 名称为 services/cache/basecache）。在服务器启动时，将始终创建缺省的对象高速缓存实例（JNDI 名称为 services/cache/distributedmap）。
1. 在管理控制台中，选择服务器> 服务器类型> WebSphere 应用程序服务器> server_name > 容器服务> 动态高速缓存服务。
2. 配置其他高速缓存设置。有关更多信息，请参阅“动态高速缓存服务设置”一文。
3. 单击应用或确定。
4. 重新启动 WebSphere® Application Server。
可以使用下列代码来查找高速缓存实例：
```
InitialContext ic = new InitialContext();
DistributedMap dm1 = (DistributedMap)ic.lookup("services/cache/instance_one");

DistributedMap dm2 = (DistributedMap)ic.lookup("services/cache/instance_two");

// or

InitialContext ic = new InitialContext();
DistributedObjectCache dm1 = (DistributedObjectCache)ic.lookup("services/cache/instance_one");

DistributedObjectCache dm2 = (DistributedObjectCache)ic.lookup("services/cache/instance_two");
```
方法 2 - 配置 Servlet 高速缓存实例。

Servlet 高速缓存实例是对缺省 Servlet 高速缓存附加的位置，动态高速缓存可以在此位置存储、分发和共享数据。使用 Servlet 高速缓存实例，您的应用程序具有更大的灵活性并且能够更好地调整高速缓存资源。对高速缓存实例指定的 Java 命名和目录接口 (JNDI) 名称将映射至 cachespec.xml 配置文件中 <cache instance> 标记中的 name 属性。

避免麻烦: 无法查找 Servlet 高速缓存。执行查找的尝试将失败并返回 null。
1. 在管理控制台中，单击资源> 高速缓存实例> Servlet 高速缓存实例。
2. 输入作用域，如下所示：
  - 指定 CELL SCOPE 来查看和配置可用于单元中的所有服务器的高速缓存实例。
  - 指定 NODE SCOPE 来查看和配置可用于具有特定节点的所有服务器的高速缓存实例。
  - 指定 SERVER SCOPE 来查看和配置仅可用于特定服务器的高速缓存实例。
3. 在“名称”字段中输入资源的必需显示名。
4. 输入资源的 JNDI 名称。在 <cache-instance> 标记中的属性字段中指定此名称cachespec.xmlconfiguration file. 此标记用于查找高速缓存条目所存储在的特定高速缓存实例。
5. 配置其他高速缓存设置。有关更多信息，请参阅“动态高速缓存服务设置”一文。
6. 单击应用或确定。
7. 可选: 如果要为此实例设置其他定制属性，请单击资源> 高速缓存实例> Servlet 高速缓存实例> servlet_cache_instance_name> 定制属性> 新建。
8. 可选: 在 "名称" 字段中输入定制属性的名称。有关更多信息，请参阅“动态高速缓存定制属性”一文。
  
  重要信息: 使用仅具有每个高速缓存实例所指示作用域的定制属性。例如，请在“名称”字段中输入 createCacheAtServerStartup。
9. 在“值”字段中，为该属性输入有效的值。
10. 保存属性并重新启动 WebSphere Application Server。
方法 3 - 配置对象高速缓存实例。

对象高速缓存实例是除缺省对象高速缓存之外的位置，动态高速缓存可以在该位置存储，分发和共享 Java Platform, Enterprise Edition (Java EE) 应用程序的数据。使用高速缓存实例赋予应用程序更佳的灵活性并调整高速缓存资源。使用 DistributedObjectCache 编程接口来访问高速缓存实例。有关 DistributedObjectCache 应用程序编程接口的更多信息，请参阅 API 文档。

注意: 方法三是方法一或方法二的扩展，列示在 "过程" 部分的开头。首先使用方法一或方法二。

创建并配置对象高速缓存实例，如下所示：
1. 在管理控制台中，单击资源> 高速缓存实例> 对象高速缓存意向。
2. 输入作用域：
  - 指定 CELL SCOPE 来查看和配置可用于单元中的所有服务器的高速缓存实例。
  - 指定 NODE SCOPE 来查看和配置可用于具有特定节点的所有服务器的高速缓存实例。
  - 指定 SERVER SCOPE 来查看和配置仅可用于特定服务器的高速缓存实例。
3. 在“名称”字段中输入资源的必需显示名。
4. 输入资源的 JNDI 名称。
  当查找对此高速缓存实例的引用时，使用此名称。结果返回 DistributedMap 对象。
5. 配置其他高速缓存设置。
  有关更多信息，请参阅“动态高速缓存服务设置”一文。
6. 单击应用或确定。
7. 可选: 如果要为此实例设置其他定制属性，请单击资源> 高速缓存实例> 对象高速缓存实例> servlet_cache_instance_name > 定制属性> 新建。
8. 可选: 在 "名称" 字段中输入定制属性的名称。
  
  重要信息: 使用仅具有每个高速缓存实例所指示作用域的定制属性。例如，请在“名称”字段中输入 createCacheAtServerStartup。
9. 在“值”字段中，为该属性输入有效的值。
10. 保存属性并重新启动 WebSphere Application Server。
如果您在管理控制台中定义了两个对象高速缓存实例，使用 JNDI 名称为 services/cache/instance_one 和 services/cache/instance_two，那么您可以使用下列代码查找高速缓存实例：
```
 InitialContext ic = new InitialContext();
DistributedMap dm1 = (DistributedMap)ic.lookup("services/cache/instance_one");

DistributedMap dm2 = (DistributedMap)ic.lookup("services/cache/instance_two");

// or

InitialContext ic = new InitialContext();
DistributedObjectCache dm1 = (DistributedObjectCache)ic.lookup("services/cache/instance_one");

DistributedObjectCache dm2 = (DistributedObjectCache)ic.lookup("services/cache/instance_two");
```
方法 4 - 使用 cacheinstances.properties 文件来配置高速缓存实例。
您可以使用 cacheinstances.properties 文件来创建高速缓存实例并将该文件打包到企业归档 (EAR) 文件中。请使用“cacheinstances.properties 文件”一文中的表信息作为名称、值和说明的参考。
第一行定义高速缓存实例名。后续各行定义定制属性。格式如下：
```
cache.instance.x=InstanceName
cache.instance.x.customPropertyName=customPropertyValue
```
其中：
- x 是起始于 0 的实例名编号。
- customPropertyName 是定制属性名。有关更多信息，请参阅“动态高速缓存定制属性”一文。
  重要信息: 将定制属性与仅针对每个高速缓存实例指示的作用域配合使用。
- customPropertyValue 是可能的定制属性值。
以下是如何使用 cacheinstances.properties创建其他高速缓存实例的示例。文件:
```
cache.instance.0=/services/cache/instance_one
cache.instance.0.cacheSize=1000
cache.instance.0.enableDiskOffload=true
cache.instance.0.diskOffloadLocation=${app_server_root}/diskOffload
cache.instance.0.flushToDiskOnStop=true
cache.instance.0.useListenerContext=true
cache.instance.0.enableCacheReplication=false
cache.instance.0.disableDependencyId=false
cache.instance.0.htodCleanupFrequency=60
cache.instance.1=/services/cache/instance_two
cache.instance.1.cacheSize=1500
cache.instance.1.enableDiskOffload=false
cache.instance.1.flushToDiskOnStop=false
cache.instance.1.useListenerContext=false
cache.instance.1.enableCacheReplication=true
cache.instance.1.replicationDomain=DynaCacheCluster
cache.instance.1.disableDependencyId=true
```
以上示例创建两个高速缓存实例，他们分别名为 instance_one 和 instance_two。高速缓存 instance_one 的高速缓存条目大小为 1,000，instance_two 的高速缓存条目大小为 1,500。在 instance_one 中启用了磁盘卸载，而此功能在 instance_two 中处于禁用状态。使用监听器上下文在 instance_one 中已启用，在 instance_two 中已禁用。 “停止时清仓到磁盘”功能在 instance_one 中处于启用状态，而在 instance_two 中处于禁用状态。在 instance_two 中启用了高速缓存复制，而此功能在 instance_one 中处于禁用状态。 instance_two 的数据复制域的名称是 DynaCacheCluster。依赖关系标识支持在 instance_two 中处于禁用状态。

请将 cacheinstances.properties 文件放在应用程序服务器或应用程序的类路径中。例如，可以使用应用程序 WAR 文件，WEB-INF\classes 目录或 server_root\classes 目录。属性文件中的第一个条目 (cache.instance.0) 指定全局名称空间中的高速缓存实例的 JNDI 名称。
您可以使用下列代码查找高速缓存实例：
```
  InitialContext ic = new InitialContext();
     DistributedMap dm1 =
(DistributedMap)ic.lookup("services/cache/instance_one");
     DistributedMap dm2 =
(DistributedMap)ic.lookup("services/cache/instance_two");

// or

InitialContext ic = new InitialContext();
DistributedObjectCache dm1 =  (DistributedObjectCache)ic.lookup("services/cache/instance_one");

DistributedObjectCache dm2 = (DistributedObjectCache)ic.lookup("services/cache/instance_two");
```
方法 5：资源引用。
重要信息: 此方法是方法三和方法四的扩展，列示在 "过程" 部分的开头。首先使用方法三或方法四。
在模块部署描述符 (web.xml 和 ibm-web-bnd.xmi 文件) 中定义 resource-ref ，并使用java:comp名称空间。以下 resource-ref 示例使用 web.xml：
```
<resource-ref id="ResourceRef_1">
		<res-ref-name>dmap/LayoutCache</res-ref-name>
		<res-type>com.ibm.websphere.cache.DistributedMap</res-type>
		<res-auth>Container</res-auth>
		<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
<resource-ref id="ResourceRef_2">
		<res-ref-name>dmap/UserCache</res-ref-name>
		<res-type>com.ibm.websphere.cache.DistributedMap</res-type>
		<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
```
以下 resource-ref 示例使用 ibm-web-bnd.xmi：
```
<?xml version="1.0" encoding="UTF-8"?>
<webappbnd:WebAppBinding xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" 
xmlns:webappbnd="webappbnd.xmi" 
xmlns:webapplication="webapplication.xmi" xmlns:commonbnd="commonbnd.xmi" 
xmlns:common="common.xmi" 
xmi:id="WebApp_ID_Bnd" virtualHostName="default_host">
		<webapp href="WEB-INF/web.xml#WebApp_ID"/>
		<resRefBindings xmi:id="ResourceRefBinding_1" 
jndiName="services/cache/instance_one">
		<bindingResourceRef href="WEB-INF/web.xml#ResourceRef_1"/>
		</resRefBindings>
		<resRefBindings xmi:id="ResourceRefBinding_2" 
jndiName="services/cache/instance_two">
		<bindingResourceRef href="WEB-INF/web.xml#ResourceRef_2"/>
		</resRefBindings>
		</webappbnd:WebAppBinding>
```
受支持的配置: 对于 IBM® 扩展和绑定文件， .xmi 或 .xml 文件扩展名有所不同，具体取决于您是使用Java EE 5 之前的应用程序或模块，还是使用 Java EE 5 或更高版本的应用程序或模块。 IBM 扩展或绑定文件名为 ibm-*-ext.xmi 或 ibm-*-bnd.xmi ，其中 * 是扩展或绑定文件的类型，例如 app， application， ejb-jar或 web。存在下列条件：
- 对于使用版本 5 之前的 Java EE 版本的应用程序或模块，文件扩展名必须为 .xmi。
- 对于使用 Java EE 5 或更高版本的应用程序或模块，文件扩展名必须为 .xml。如果应用程序或模块随附 .xmi 文件，那么产品会忽略 .xmi 文件。
但是， Java EE 5 或更高版本的模块可以存在于包含Java EE 5 之前的文件并使用 .xmi 文件扩展名的应用程序中。

ibm-webservices-ext.xmi、ibm-webservices-bnd.xmi、ibm-webservicesclient-bnd.xmi、ibm-webservicesclient-ext.xmi 和 ibm-portlet-ext.xmi 文件继续使用 .xmi 文件扩展名。
下列示例显示如何查找 resource-ref：
```
InitialContext ic = new InitialContext();
  DistributedMap dm1a =(DistributedMap)ic.lookup("java:comp/env/dmap/LayoutCache");
  DistributedMap dm2a =(DistributedMap)ic.lookup("java:comp/env/dmap/UserCache");
// or
  DistributedObjectCache dm1a =(DistributedObjectCache)ic.lookup("java:comp/env/dmap/LayoutCache");
  DistributedObjectCache dm2a =(DistributedObjectCache)ic.lookup("java:comp/env/dmap/UserCache");
```
上一个 resource-ref 示例将 java:comp/env/dmap/LayoutCache 映射至 /services/cache/instance_one，并将 java:comp/env/dmap/UserCache 映射至 /services/cache/instance_two。在这些示例中，DistributedMap dm1 和 dm1a 是同一个对象。 DistributedMap dm2 和 dm2a 是同一个对象。
方法 6 :Java 虚拟机高速缓存设置。
您可以采用全局方式来设置定制属性，以便影响所有高速缓存实例。这将覆盖方法 1、方法 2 和方法 3 中的设置，但不会覆盖方法 4 (cacheinstances.properties) 中的设置。请以全局方式配置高速缓存实例，如下所示：
1. 在管理控制台中，单击服务器> 服务器类型> WebSphere 应用程序服务器> server_name > Java 和进程管理> 进程定义> Java 虚拟机> 定制属性> 新建。
2. 在“名称”字段中输入定制属性的名称。有关更多信息，请参阅“动态高速缓存定制属性”一文。找到定制属性名称后，添加com.ibm.ws.cache.CacheConfig前缀到定制属性名称的前面。例如，如果定制属性名是 createCacheAtServerStartup，请在“名称”字段中输入 com.ibm.ws.cache.CacheConfig.createCacheAtServerStartup。
3. 在“值”字段中，为该属性输入有效的值。
4. 保存属性并重新启动 WebSphere Application Server。