用于记录的 JRas 编程接口(不推荐)
不推荐使用本任务及其子任务中描述的 JRas 框架。但是,可以使用 Java™ 记录来获得类似结果。
一般注意事项
您可以配置 WebSphere® Application Server 以使用 Java 2 安全性限制对受保护资源(例如,文件系统和套接字)的访问。因为用户编写的扩展通常访问这种受保护资源,所以用户编写的扩展必须使用 AccessController doPrivileged 调用来包含相应的安全性检查调用。另外,用户编写的扩展必须包含相应的策略文件。通常,在单独的包中找到用户编写的扩展是好的实践。您有职责适当地限制对用户编写的扩展的访问。
编写处理程序
用户编写的处理程序必须实现 RASIHandler 接口。RASIHandler 接口扩展 RASIMaskChangeGenerator 接口,而该接口又扩展 RASIObject 接口。下面对每个这样的接口所引入的方法以及实现指针进行简短的讨论。获取有关任何这类特殊接口或方法的更详细信息,请参阅相应的产品 API 文档。
RASIObject 接口
- 独立 JRas 记录工具箱支持基于基本属性文件的配置。要实现此配置支持,配置状态作为一组“键/值”对存储在属性文件中。方法 public Hashtable getConfig 和 public void setConfig(Hashtable ht) 用于获取和设置此配置状态。JRas 扩展不支持基于属性的配置。请将这些方法作为无操作来实现。可以使用这些方法来实现基于您自己的属性的配置。
- 记录器、处理程序和格式化程序可以是指定对象。例如,JRas 扩展要求用户为从管理器检索的记录器提供名称。您额可以命名您的处理程序。提供了 public String getName 和 public void setName(String name) 方法,以获取或设置名称字段。JRas 扩展当前在用户处理程序上不调用这些方法。可以如您所愿地实现这些方法,也包含无操作。
- 记录器、处理程序和格式化程序还可以包含描述字段。方法 public String getDescription 和 public void setDescription(String desc) 可用于获取或设置描述字段。JRas 扩展当前不使用描述字段。可以如您所愿地实现这些方法,也包含无操作。
- 提供了方法 public String getGroup 以供 RASManager 接口使用。由于 JRas 扩展提供自己的管理器类,所以从不调用此方法。请将此作为无操作来实现。
RASIMaskChangeGenerator 接口
RASIMaskChangeGenerator 接口是基于掩码状态定义过滤事件的实现方法的接口。它当前通过记录器和处理程序实现。通过定义,实现此接口的对象包含消息掩码和跟踪掩码,尽管可能不需要使用它们。例如,消息记录器包含跟踪掩码,但从不使用跟踪掩码,因为此消息记录器从不生成跟踪事件。但是,处理程序可以高效地使用这两个掩码值。例如,单个处理程序可以处理消息和跟踪事件。
- public long getMessageMask 和 public void setMessageMask(long mask) 方法用于获取或设置消息掩码值。public long getTraceMask 和 public void setTraceMask(long mask) 方法用于获取或设置跟踪掩码值。
另外,此接口还为有关各方引入掩码更改状态时回调的概念。callback 对象必须实现 RASIMaskChangeListener 接口。
- 方法 public void addMaskChangeListener(RASIMaskChangeListener listener) 和 public void removeMaskChangeListener(RASIMaskChangeListener listener) 用于添加或移除处理程序的侦听器。方法 public Enumeration getMaskChangeListeners 会在当前已注册的侦听器列表上返回一个枚举。方法 public void fireMaskChangedEvent(RASMaskChangeEvent mc) 用于回调所有已注册的侦听器,以通知它们掩码更改事件。
由于效率原因,JRas 扩展消息和跟踪记录器实现 RASIMaskChangeListener 接口。记录器实现除了维护记录器掩码外,还维护组合掩码。记录器组合掩码通过对已向该记录器注册的所有处理程序的相应掩码进行逻辑 or 处理,然后对记录器掩码结果进行 and 处理形成。例如,消息记录器组合掩码通过已向该记录器注册的所有处理程序的消息掩码进行 or 处理,然后对记录器消息掩码结果进行 and 处理形成。
要求所有处理程序都正确地实现这些方法。另外,当初始化用户处理程序时,添加的记录器必须已向处理程序注册;请使用 addMaskChangeListener 方法。当处理程序的消息掩码或跟踪掩码更改时,必须回调记录器以通知它掩码更改。通过此过程,记录器可以动态地维护组合掩码。
RASMaskChangedEvent 类由独立的 JRas 记录工具箱定义。在此上下文中,支持由用户代码直接使用该类。
另外,RASIMaskChangeGenerator 接口还引入了高速缓存实现对象处理的所有消息和跟踪事件类的名称的概念。这些方法的目的是支持管理程序如图形用户界面检索名称列表和内省类,以确定可能处理的事件类型和显示结果。JRas 扩展未曾调用这些方法,因此可作为无操作实现。
- 可调用方法 public void addMessageEventClass(String name) 和 public void removeMessageEventClass(String name),以从列表中添加或移除消息事件类名。方法 public Enumeration getMessageEventClasses 会在消息事件类名的列表上返回一个枚举。同样,可调用方法 public void addTraceEventClass(String name) 和 public void removeTraceEventClass(String name),以从列表中添加或移除跟踪事件类名。方法 public Enumeration getTraceEventClasses 会在跟踪事件类名的列表上返回一个枚举。
RASIHandler 接口
RASIHandler 接口引入特定于处理程序行为的方法。
由独立的 JRas 记录工具箱提供的 RASIHandler 接口支持以同步或异步方式运行的处理程序。在异步方式下,通常通过调用线程来排队事件,然后由工作程序线程写入事件。因为在 WebSphere Application Server 环境中不支持衍生线程,所以期望处理程序不对事件进行排队或批处理,尽管没有明确禁止此活动。
- 方法 public int getMaximumQueueSize() 和 public void setMaximumQueueSize(int size) 产生 IllegalStateException 异常,以管理最大队列大小。提供了方法 public int getQueueSize 以查询实际队列长短。
- 方法 public int getRetryInterval 和 public void setRetryInterval(int interval) 支持错误重试概念,这暗示某种类型的排队。
- 提供了方法 public void addFormatter(RASIFormatter formatter)、public void removeFormatter(RASIFormatter formatter) 和 public Enumeration getFormatters,以管理配置处理程序所使用的格式化程序列表。如果适当,可为不同事件类提供不同格式化程序。
- 提供了方法 public void openDevice、public void closeDevice 和 public void stop,以管理处理程序摘要的底层设备。
- 提供了方法 public void logEvent(RASIEvent event) 和 public void writeEvent(RASIEvent event),以将事件传递到处理程序进行处理。
编写格式化程序
用户编写的格式化程序必须实现 RASIFormatter 接口。RASIFormatter 接口扩展 RASIObject 接口。RASIObject 接口的实现对于处理程序和格式化程序是相同的。下面对 RASIFormatter 接口引入的方法进行简短的讨论。有关此接口引入的方法的更详细信息,请参阅相应的产品 API 文档。
RASIFormatter 接口
- 由独立 JRas 记录工具箱提供的具体 RASHandler 类使用方法 public void setDefault(boolean flag) 和 public boolean isDefault 来确定某一特殊格式化程序是否为缺省格式化程序。因为这些 RASHandler 类不得在 WebSphere Application Server 环境中使用,所以这些方法的语义可以由用户确定。
- 提供了方法 public void addEventClass(String name)、public void removeEventClass(String name) 和 public Enumeration getEventClasses,以确定格式化程序可使用哪些事件类进行格式化。可以提供适当的实现。
- 方法 public String format(RASIEvent event) 由处理程序对象调用,并且返回事件的已格式化字符串说明。