When you create the component-events.xml audit definition file, keep in mind the following points:

• Any change to an audit event definition requires that the version ID be modified by changing the minor or major numbers.

• There must be a 1-to-1 correspondence between tables for your application attribute definitions and database columns. Each custom attribute must have a corresponding order number in its definition.

The following procedure explains how to generate the XLIFF (XML Localization Interchange File Format) translations files and pack them in the component_events_xlf.jar file. At deployment and during registration, this information is stored in the audit store along with the component event definition.

This section explains the two methods by which declarative registration of audit definitions occurs:

The following example shoes how to register an application with audit programmatically:

AuditService auditService = JpsServiceLocator.getServiceLocator().lookup(AuditService.class);
AuditRegistration auditReg = <instance of AuditRegistration implementation>;
AccessController.doPrivileged(new PrivilegedExceptionAction<Object>() {
            public Object run() throws AuditException, IOException {
                auditService.register(auditReg);
                return null;
            }
        });

Calling the auditService.register method requires that the application be granted the AuditStoreAccessPermission permission with create, upgrade actions. For information about specifying grants, see Setting System Grants.

Here is a programmatic registration example:

JpsContextFactory ctxFactory = JpsContextFactory.getContextFactory();
JpsContext ctx = ctxFactory.getContext();
//get audit service
final AuditService auditService = ctx.getServiceInstance(AuditService.class);

//create an audit registration instance
final AuditRegistration auditReg = new SampleRegistration();
 
//call API to register audit event definition
AccessController.doPrivileged(new PrivilegedExceptionAction<Object>() {
      public Object run() throws AuditException, IOException {
      auditService.register(auditReg);
      return null;
   }
});

Registration creates a database view to query audit records from the database. To add logic to manage view creation or to disable this feature, implement the interface oracle.security.jps.service.audit.AuditRegistrationExt, an interface that extends AuditRegistration:

SampleRegistration.java
class SampleRegistration implements AuditRegistrationExt {
  /* 
    methods from Audit Registration go here
   */
  public AuditRegistrationExt.TYPE getIAUViewSupportType() {
     // add app specific logic here to determine the type
    return AuditRegistrationExt.TYPE.<type>;  // where type is SIMPLE, INDEXABLE, DISABLE
  }
} 

To register your application with audit, use the registerAudit WebLogic Scripting Tool (WLST) command. This command also allows you to create an audit view with the registration:

registerAudit(xmlFile, [xlfFile], componentType, [mode=OVERWRITE|UPGRADE], [createView=SIMPLE|INDEXABLE|DISABLE]) 

where SIMPLE is the default if no value is provided for createView.

See registerAudit in the WLST Command Reference for Infrastructure Security.

When a domain is created or extended, applications can specify the seeding of application-specific security data in the security store. For information about artifact seeding, see How Security Artifacts Are Seeded.

Jakarta EE applications can register with audit by means of domain extension templates containing the component_events.xml and component_events_xlf.jar files. Audit registration processes them automatically when you deploy the application. For information about the files included in the template, see Layered Component Security Artifacts.

To query audit data, use any of the following methods:

Set<String> getComponentNames() throws AuditException;
Map<String, ? extends AttributeGroup> getGenericAttributeGroups() throws AuditException;
    Collection<? extends EventCategory> getSystemEvents() throws AuditException;
    ComponentDefinition getComponentDef(String componentType) throws AuditException;
    AttributesDatabaseMap getAttributesMap(String componentType) throws AuditException;
    AttributesDatabaseMap getSystemAttributesMap() throws AuditException;

The following example demonstrates how to query audit data:

 //search events and attributes for a component
    Set<String> components = auditAdminService.getComponentNames();
    for (String componentType : components) {
        ComponentDefinition componentDef = auditAdminService.getComponentDef(componentType);
        //get attributes of a component
        AttributeGroup attrGroup = componentDef.getAttributes();
        for (AuditAttribute attr : attrGroup.getAttributes()) {
            AuditAttribute.DataType type = attr.getAttributeType();
            String attrName = attr.getName();
        }
        //get events of a component
        Collection<? extends EventCategory> events = componentDef.getEvents();
        for (EventCategory category : events) {
            if (category.isComponentSpecific()) { // isComponentSpecific() is true means the category is belong to a component, otherwise is system category
                Collection<? extends Event> categoryEvents = category.getAllEvents();
 
            }
        }
    }

To retrieve and set an audit policy, use the following methods:

AuditPolicy getAuditPolicy(String componentType) throws AuditException;
void setAuditPolicy(String componentType, AuditPolicy auditPolicy) throws AuditException;

The following example shows how to use these methods to obtain and set the audit policy for a component:

 //get runtime policy for component JPS
    final String componentType = "JPS";
    AuditPolicy policy = auditAdminService.getAuditPolicy(componentType);
    String filterLevel = policy.getFilterLevel();
 
    //set runtim policy for component JPS
    final AuditPolicy newPolicy = new AuditPolicy("None", null, null);
    //setAuditPolicy() requires AuditStoreAccessPermission(<componentType>, "modify");
    AccessController.doPrivileged(new PrivilegedExceptionAction<Object>(){
        public Object run() throws AuditException {
            auditAdminService.setAuditPolicy(componentType, newPolicy);
            return null;
        }
    });

The Audit Framework provides the following class and interfaces:

Interface AuditService {
Auditor getAuditor(String componentType);
void register(AuditRegistration auditRegistration);
void unregister(AuditRegistration auditRegistration);
}
Interface Auditor {
boolean log(AuditEvent ev);
boolean isEnabled();
boolean isEnabled(String categoryName, String eventType, boolean eventStatus, Map<String, Object> properties);
}
public class oracle.security.jps.service.audit.AuditEvent {
   public AuditEvent(AuditContext ctx, String eventType, 
    String eventCategory, boolean eventStatus, String messageText);
   public void setApplicationName(String applicationName)   public void setAttribute(String attributeName, Object attributeValue)   public void setAttributeBoolean(String attributeName, boolean attributeValue)   public void setAttributeBoolean(String attributeName, Boolean attributeValue)   public void setAttributeBooleans(String attributeName, boolean[] values)   public void setAttributeByteArray(String attributeName, byte[] attributeValue)   public void setAttributeDate(String attributeName, Date attributeValue)   public void setAttributeDates(String attributeName, Date[] values)   public void setAttributeDouble(String attributeName, double attributeValue)   public void setAttributeDoubles(String attributeName, double[] values)   public void setAttributeFloat(String attributeName, float attributeValue)   public void setAttributeFloats(String attributeName, float[] values)   public void setAttributeInt(String attributeName, int attributeValue)   public void setAttributeInts(String attributeName, int[] values)   public void setAttributeLong(String attributeName, long attributeValue)   public void setAttributeLongs(String attributeName, long[] values)   public void setAttributeString(String attributeName, String attributeValue)   public void setAttributeStrings(String attributeName, String[] values)   public void setComponentName(String componentName)   public void setComponentType(String componentType)   public void setContextFields(String contextFields)   public void setECID(String ecid)   public void setEventCategory(String category)   public void setEventDefinition(Object
eventDefinition)   public void setEventStatus(boolean status)   public void setEventTimestamp(long eventTimestamp)   public void setEventType(String eventType)   public void setFailureCode(String failureCode)   public void setHostId(String hostId)   public void setHostNetworkAddr(String hostNetworkAddr)   public void setInitiator(String initiator)   public void setInstanceId(String instanceId)   public void setMessageText(String messageText)   public void setModuleId(String moduleId)   public void setOracleHome(String oracleHome)   public void setOracleInstance(String oracleInstance)   public void setProcessId(String processId)   public void setRemoteIP(String value)              public void setResource(String value)             public void setRID(String rid)             public void setRoles(String value)            public void setTarget(String value)           public void setTargetComponentType(String targetComponentType)            public void setThreadId(String threadId)   public void setTransactionId(String transactionId)
}

To set permissions and to obtain an auditor instance, see Setting System Grants, and Obtaining the Auditor Instance.

Applications must have the AuditStoreAccessPermission permission to use methods provided by the Audit Framework. In this example, the grant allows the MyApp application to call the auditService.getAuditor method in an AccessController.doPrivileged block:

<grant>
  <grantee>
    <codesource>
      <url>file:${oracle.deployed.app.dir}/MyApp${oracle.deployed.app.ext}</url>
    </codesource>
  </grantee>
 <permissions>
  <permission>
    <class>oracle.security.jps.service.audit.AuditStoreAccessPermission</class>
    <name>comp1</name>
    <actions>action1,action2,action3</actions>
  </permission>
 </permissions>
</grant>

where the <actions> is the comma-separated list of actions that the application can carry out. The following table lists the available actions:

After your application registers to audit, it can get its auditor instance programmatically:

//Gets audit service instance
final AuditService auditService = JpsServiceLocator.getServiceLocator().lookup(AuditService.class);
 
//Gets Auditor instance for application 'MyApp'
Auditor auditor = AccessController.doPrivileged(
                            new PrivilegedExceptionAction<Auditor>() {
                                public Auditor run() throws AuditException {
                                    return auditService.getAuditor("MyApp");
                                }
                            });
 
final String category = "Transaction";
final String eventName = "deposit";
 
//Check if event 'deposit' is enabled in filtering.
boolean enabled = auditor.isEnabled(category, eventName, "true", null);
if (enabled) {
        AuditContext ctx = new AuditContext();
        String message = "deposit transaction";
        //Creates an audit event
        AuditEvent ev = new AuditEvent(ctx, eventName, category, "true", message);
 
        //Sets event attributes
        ev.setInitiator("johnsmith");
        ev.setAttributeInt("accounting:AccountNumber", 2134567);
        ev.setAttributeDate("accounting:Date", new Date());
        ev.setAttributeFloat("accounting:Amount", 100.00);
 
        //Logs audit event
        boolean ret = auditor.log(event);
}