Soporte de JSR-047 y anotaciones comunes
El analizador de anotaciones y rastreo proporciona soporte autónomo y de
conectores para usuarios nuevos y existentes de las utilidades de registro cronológico de
anotaciones siguientes:
- Las API de anotaciones Java JSR-047
- Las anotaciones comunes
A continuación se proporcionan los detalles de este soporte.
- Capacidad para exportar mensajes de anotaciones a un agente de anotaciones
Extensión de la clase abstracta java.util.logging.Handler
del paquete org.eclipse.hyades.logging.java que permite configurar los
anotadores para que exporten mensajes de anotaciones a un agente de
anotación.
Este manejador org.eclipse.hyades.logging.java.LoggingAgentHandler
comprueba si un mensaje de anotaciones de java.util.logging.LogRecord
escrito en un anotador se puede anotar tomando como base el filtro del
manejador y su nivel de anotación. Si el mensaje de anotaciones se anotará,
se crea un agente de anotación con el mismo nombre que el anotador que anota el
mensaje. El mensaje se formatea mediante una clase
org.eclipse.hyades.logging.java.XmlFormatter y se escribe en el agente
de anotación.
- Capacidad para convertir los mensajes de anotaciones en
XML
Una extensión de la clase abstracta java.util.logging.Formatter del
paquete org.eclipse.hyades.logging.java permite que la clase
org.eclipse.hyades.logging.java.LoggingAgentHandler y otros
manejadores formateen los mensajes de anotaciones de
java.util.logging.LogRecord en XML. Este formateador
org.eclipse.hyades.logging.java.XmlFormatter convierte el mensaje de
java.util.logging.LogRecord en su equivalente XML en la implementación
actual de org.eclipse.hyades.internal.logging.core.XmlGenerator, pero
excluye los códigos de sistema principal, proceso y agente (host, process,
agent). El XML generado no está formateado y su nivel máximo de anidación se
establece en 4. Cuando se formatea, se comprueba el objeto para ver si
implementa la interfaz
org.eclipse.hyades.logging.core.IExternalizableToXml. Si la
implementa, por cuestión de rendimiento se llama a la API
externalizeCanonicalXmlString(), en lugar de realizar la serialización
de XML por medio de la introspección.
Los siguientes datos de salida ilustran la conversión XML de un mensaje de
anotaciones (la serie "Hello World" (nivel de anotación SEVERE (grave))):
<LogRecord logging.util.id="java.util.logging.LogRecord_10468105484720000"
logging.util.agent_idref="org.eclipse.hyades.tests.java.JavaLoggingTest"
logging.util.MsgLoggerLevel="SEVERE" LoggerName="org.eclipse.hyades.tests.java.JavaLoggingTest"
ResourceBundleName="null" SequenceNumber="0" SourceClassName="org.eclipse.hyades.tests.java.JavaLoggingTest"
SourceMethodName="main" Message="Hello World" ThreadID="10"
Millis="1046810548171">
<ResourceBundle Instance_Name="ResourceBundle" Value="null"/>
<Level Instance_Name="Level" logging.util.id="java.util.logging.Level_10468105484720001"
ResourceBundleName="sun.util.logging.resources.logging" Name="SEVERE"
LocalizedName="SEVERE"><Class Instance_Name="Class" logging.util.id="java.lang.Class_10468105484720002"
Name="java.util.logging.Level" Type="class" Package="java.util.logging"
Modifers="public" Superclass="java.lang.Object" />
</Level>
<Array Instance_Name="Parameters" Value="null" />
<Throwable Instance_Name="Thrown" Value="null" />
<Class Instance_Name="Class" logging.util.id="java.lang.Class_10468105484820000"
Name="java.util.logging.LogRecord" Type="class" Package="java.util.logging"
Modifers="public" Superclass="java.lang.Object" />
</LogRecord>
- Capacidad para cargar clases de extensión en las API de anotación Java existentes
Para cargar las clases de extensión org.eclipse.hyades.logging.java14
en las API de anotación Java existentes en el JDK 1.4.0 y superior, debe añadir
las siguientes entradas al archivo de configuración
JRE_HOME\lib\logging.properties antes del inicio de la VM o antes de
que se llame a la API java.util.logging.LogManager.readConfiguration():
handlers= <sus manejadores actuales>, org.eclipse.hyades.logging.java.LoggingAgentHandler
org.eclipse.hyades.logging.java.LoggingAgentHandler.formatter = org.eclipse.hyades.logging.java.XmlFormatter
Otra posibilidad es que utilice las clases de extensión del conector
org.eclipse.hyades.logging.java14 con las API de anotación Java
existentes en el JDK 1.4.0 y superior en el anotador (por ejemplo, handler) y
en el manejador (por ejemplo, formatter) programáticamente en tiempo de
ejecución mediante las API addHandler() y setFormatter(),
respectivamente.
- Capacidad para incluir un evento base común (CBE) en un registro
de anotaciones
Una extensión de la clase java.util.logging.LogRecord del paquete
org.eclipse.hyades.logging.java le permite crear un registro de
anotaciones personalizado para incluir una interfaz
org.eclipse.hyades.logging.events.ICommonBaseEvent en una clase
java.util.logging.LogRecord.
Este objeto simple
org.eclipse.hyades.logging.java.CommonBaseEventLogRecord amplía la
clase java.util.logging.LogRecord y contiene una sola referencia a una
interfaz org.eclipse.hyades.logging.events.ICommonBaseEvent. Usted
tendrá que encargarse de crear un objeto
org.eclipse.hyades.logging.java.CommonBaseEventLogRecord nuevo antes
de escribir en el anotador java.util.logging.Logger.
- Capacidad para permitir el filtrado de registros anotados para
que la clase de manejador no los procese
Puede filtrar los registros anotados para que la clase
org.eclipse.hyades.logging.java.LoggingAgentHandler no los procese,
estableciendo para ello una implementación de la interfaz
java.util.logging.Filter como
org.eclipse.hyades.logging.java.CommonBaseEventFilter (solo permite
que se anote satisfactoriamente el registro
org.eclipse.hyades.logging.java.CommonBaseEventLogRecord) y la
anotación a nivel java.util.logging.Level en el manejador. Estos valores se
pueden establecer programáticamente en tiempo de ejecución con las API
setFilter() y setLevel(), respectivamente.
Otra posibilidad sería añadir las siguientes entradas al archivo de
configuración JRE_HOME\lib\logging.properties antes de que se inicie
la VM o antes de que se llame a la API
java.util.logging.LogManager.readConfiguration():
org.eclipse.hyades.logging.java.LoggingAgentHandler.level = <nivel>
org.eclipse.hyades.logging.java.LoggingAgentHandler.filter = org.eclipse.hyades.logging.java.CommonBaseEventFilter
- Capacidad para crear un anotador personalizado para
los java.lang.Object y los java.lang.Throwable
Una implementación de la interfaz
org.apache.commons.logging.Log del paquete
org.eclipse.hyades.logging.commons le permite crear un anotador
personalizado para anotar los java.lang.Object y los
java.lang.Throwable en un agente de anotación que tenga el mismo
nombre que el anotador.
Este anotador org.eclipse.hyades.logging.commons.Logger comprueba si
los mensajes de anotaciones de java.lang.Object y/o
java.lang.Throwable escritos en un anotador se pueden anotar tomando
como base el nivel de anotación del anotador. Si el mensaje de anotaciones se
anotará, el mensaje de anotaciones de java.lang.Object y
java.lang.Throwable se formatea con un
org.eclipse.hyades.internal.logging.core.XmlGenerator y se escribe en
el agente de anotación. Cuando se formatea, se comprueba el objeto para ver si
implementa la interfaz
org.eclipse.hyades.logging.core.IExternalizableToXml. Si la
implementa, por cuestión de rendimiento se llama a la API
externalizeCanonicalXmlString(), en lugar de realizar la serialización
de XML por medio de la introspección. Para cargar la clase
org.eclipse.hyades.logging.commons.Logger en la clase
org.apache.commons.logging.LogFactory, debe establecer la siguiente
propiedad del sistema en el momento del inicio de la VM:
-Dorg.apache.commons.logging.Log=org.eclipse.hyades.logging.commons.Logger
Precauciones
- Si anota los mensajes de anotaciones de tipo serie, no debe incorporar
los fragmentos XML en el mensaje. Si incorpora fragmentos XML en el mensaje de
anotaciones, el contenido XML quedará normalizado y se añadirá al valor del
atributo value de un código de tipo serie. Por ejemplo:
<String >logging.util.agent_idref>=>"AGENT_CREATE.LoggingUtilSample
logger.1045075846.538" >logging.util.MsgLoggerLevel>=>"FINEST"
>Value>=>"<tag attribute="value"/>">/>>
- Si utiliza las rutinas de registro cronológico autónomas
com.ibm.etools.logging.util, debe añadir la vía de acceso a los
archivos JAR hlcore.jar, hparse.jar, hexl.jar y hexr.jar a la vía de
acceso de clases de la VM y del sistema.
Conceptos relacionados
Modelo de evento base común
(C) Copyright IBM Corporation 2000, 2003. Reservados todos los derechos.