001/* 002 * The contents of this file are subject to the terms of the Common Development and 003 * Distribution License (the License). You may not use this file except in compliance with the 004 * License. 005 * 006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the 007 * specific language governing permission and limitations under the License. 008 * 009 * When distributing Covered Software, include this CDDL Header Notice in each file and include 010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL 011 * Header, with the fields enclosed by brackets [] replaced by your own identifying 012 * information: "Portions copyright [year] [name of copyright owner]". 013 * 014 * Copyright 2015 ForgeRock AS. 015 */ 016 017package org.forgerock.audit.events.handlers; 018 019import java.util.Set; 020 021import org.forgerock.services.context.Context; 022import org.forgerock.json.JsonValue; 023import org.forgerock.json.resource.ActionRequest; 024import org.forgerock.json.resource.ActionResponse; 025import org.forgerock.json.resource.QueryRequest; 026import org.forgerock.json.resource.QueryResourceHandler; 027import org.forgerock.json.resource.QueryResponse; 028import org.forgerock.json.resource.ResourceException; 029import org.forgerock.json.resource.ResourceResponse; 030import org.forgerock.util.promise.Promise; 031 032/** 033 * The interface for an AuditEventHandler. 034 * <p/> 035 * Implementations may make use of {@link org.forgerock.audit.DependencyProvider} to obtain dependencies from 036 * the product within which the audit service is deployed. Where DependencyProvider is used, the dependencies 037 * that it is expected to provide should be clearly documented. 038 */ 039public interface AuditEventHandler { 040 041 /** 042 * Instruct this object that it is safe to initialize file handles and network connections. 043 * <p/> 044 * Reconfiguration of the {@link org.forgerock.audit.AuditService} and its handlers is achieved by replacing 045 * rather than modifying the existing objects. Therefore, it's essential that the replacements do not perform 046 * any I/O that would interfere with the operation of the objects they are replacing until the old objects are 047 * shutdown. For example, when shutting down an old instance of a file-based AuditEventHandler, the old instance 048 * may need to flush buffers, apply file rotation or retention policies, or even add line or block signatures 049 * as part of tamper evident logging. Any of these operations could be broken if two handler instances are 050 * operating on the same set of files simultaneously. 051 * 052 * @throws ResourceException if starting the AuditEventHandler fails 053 */ 054 void startup() throws ResourceException; 055 056 /** 057 * Instruct this object to flush any buffers and close any open file handles or network connections. 058 * 059 * @throws ResourceException if closing the AuditEventHandler fails 060 */ 061 void shutdown() throws ResourceException; 062 063 /** 064 * Gets the name of this audit event handler. 065 * @return this handler's name. 066 */ 067 String getName(); 068 069 /** 070 * Gets the names of all audit event topics this handler is registered against. 071 * @return the names of all topics handled by this object. 072 */ 073 Set<String> getHandledTopics(); 074 075 /** 076 * Publishes an event to the provided topic. 077 * 078 * @param context 079 * The context chain that initiated the event. 080 * @param topic 081 * The topic where to publish the event. 082 * @param event 083 * The event to publish. 084 * @return a promise with either a response or an exception 085 */ 086 Promise<ResourceResponse, ResourceException> publishEvent(Context context, String topic, JsonValue event); 087 088 /** 089 * Reads an event with the provided resource id from the provided topic. 090 * 091 * @param context 092 * The context chain that initiated the event. 093 * @param topic 094 * The topic where event is read. 095 * @param resourceId 096 * The identifier of the event. 097 * @return a promise with either a response or an exception 098 */ 099 Promise<ResourceResponse, ResourceException> readEvent(Context context, String topic, String resourceId); 100 101 /** 102 * Query some events from the provided topic. 103 * 104 * @param context 105 * The context chain that initiated the event. 106 * @param topic 107 * The topic on which query is performed. 108 * @param query 109 * The request with the query. 110 * @param handler 111 * The handler to process responses for the query. 112 * @return a promise with either a response or an exception 113 */ 114 Promise<QueryResponse, ResourceException> queryEvents(Context context, String topic, QueryRequest query, 115 QueryResourceHandler handler); 116 117 /** 118 * Checks if the audit event handler is enabled. 119 * @return whether or not the audit event handler is enabled 120 */ 121 boolean isEnabled(); 122 123 /** 124 * Performs an action. 125 * 126 * @param context 127 * The context chain that initiated the event. 128 * @param topic 129 * The topic on which action is performed. 130 * @param request 131 * The request with the action. 132 * @return a promise with either a response or an exception 133 */ 134 Promise<ActionResponse, ResourceException> handleAction(Context context, String topic, ActionRequest request); 135}