/*
* Copyright (C) 2005-2010 Alfresco Software Limited.
*
* This file is part of Alfresco
*
* Alfresco is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* Alfresco is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with Alfresco. If not, see .
*/
package org.alfresco.service.cmr.audit;
import java.io.Serializable;
import java.util.List;
import java.util.Map;
import org.alfresco.service.NotAuditable;
import org.alfresco.service.PublicService;
import org.alfresco.service.cmr.repository.NodeRef;
/**
* The public API by which applications can create audit entries.
* This does not affect auditing using method interceptors.
* The information recorded can not be confused between the two.
*
* This API could be used by an audit action.
*
* @author Andy Hind
*/
@PublicService
public interface AuditService
{
/**
* Add an application audit entry.
*
* @param source -
* a string that represents the application
* @param description -
* the audit entry
*/
@NotAuditable
public void audit(String source, String description);
/**
*
* @param source -
* a string that represents the application
* @param description -
* the audit entry
* @param key -
* a node ref to use as the key for filtering etc
*/
@NotAuditable
public void audit(String source, String description, NodeRef key);
/**
*
* @param source -
* a string that represents the application
* @param description -
* the audit entry
* @param args -
* an arbitrary list of parameters
*/
@NotAuditable
public void audit(String source, String description, Object... args);
/**
*
* @param source -
* a string that represents the application
* @param description -
* the audit entry *
* @param key -
* a node ref to use as the key for filtering etc
* @param args -
* an arbitrary list of parameters
*/
@NotAuditable
public void audit(String source, String description, NodeRef key, Object... args);
/**
* Get the audit trail for a node ref.
*
* @param nodeRef - the node ref for which to get the audit trail.
* @return - tha audit trail
*/
@NotAuditable
public List getAuditTrail(NodeRef nodeRef);
/*
* V3.2 from here on. Put all fixes to the older audit code before this point, please.
*/
/**
* @param applicationName the name of the application to check
* @param path the path to check
* @return Returns true if auditing is enabled for the given path
*
* @since 3.2
*/
boolean isAuditEnabled(String applicationName, String path);
/**
* Enable auditing for an application path
*
* @param applicationName the name of the application to check
* @param path the path to enable
*
* @since 3.2
*/
void enableAudit(String applicationName, String path);
/**
* Disable auditing for an application path
*
* @param applicationName the name of the application to check
* @param path the path to disable
*
* @since 3.2
*/
void disableAudit(String applicationName, String path);
/**
* Remove all audit entries for the given application
*
* @param applicationName the name of the application for which to remove entries
*
* @since 3.2
*/
void clearAudit(String applicationName);
/**
* The interface that will be used to give query results to the calling code.
*
* @since 3.2
*/
public static interface AuditQueryCallback
{
/**
* Determines whether this callback requires the values argument to be populated when {@link #handleAuditEntry}
* is called.
*
* @return true if this callback requires the values argument to be populated
*/
boolean valuesRequired();
/**
* Handle a row of audit entry data.
*
* @param entryId the unique audit entry ID
* @param applicationName the name of the application
* @param user the user that logged the entry
* @param time the time of the entry
* @param values the values map as created
* @return Return true to continue processing rows or false to stop
*/
boolean handleAuditEntry(
Long entryId,
String applicationName,
String user,
long time,
Map values);
/**
* Handle audit entry failures
*
* @param entryId the entry ID
* @param errorMsg the error message
* @param error the exception causing the error (may be null)
* @return Return true to continue processing rows or false to stop
*/
boolean handleAuditEntryError(Long entryId, String errorMsg, Throwable error);
}
/**
* Issue an audit query using the given parameters and consuming results in the callback.
*
* @param callback the callback that will handle results
* @param parameters the parameters for the query (may not be null)
* @param maxResults the maximum number of results to retrieve (zero or negative to ignore)
*
* @since 3.3
*/
void auditQuery(AuditQueryCallback callback, AuditQueryParameters parameters, int maxResults);
/**
* Get the audit entries that match the given criteria.
*
* @param callback the callback that will handle results
* @param forward true for results to ordered from first to last,
* or false to order from last to first
* @param applicationName if not null, find entries logged against this application
* @param user if not null, find entries logged against this user
* @param from the start search time (null to start at the beginning)
* @param to the end search time (null for no limit)
* @param maxResults the maximum number of results to retrieve (zero or negative to ignore)
*
* @since 3.2
* @deprecated Use {@link #auditQuery(AuditQueryCallback, AuditQueryParameters)}
*/
void auditQuery(
AuditQueryCallback callback,
boolean forward,
String applicationName, String user, Long from, Long to,
int maxResults);
/**
* Get the audit entries that match the given criteria.
*
* @param callback the callback that will handle results
* @param forward true for results to ordered from first to last,
* or false to order from last to first
* @param applicationName if not null, find entries logged against this application
* @param user if not null, find entries logged against this user
* @param from the start search time (null to start at the beginning)
* @param to the end search time (null for no limit)
* @param searchKey the audit key path that must exist (null to ignore)
* @param searchValue an audit value that must exist (null to ignore)
* @param maxResults the maximum number of results to retrieve (zero or negative to ignore)
*
* @since 3.2
* @deprecated Use {@link #auditQuery(AuditQueryCallback, AuditQueryParameters)}
*/
void auditQuery(
AuditQueryCallback callback,
boolean forward,
String applicationName, String user, Long from, Long to,
String searchKey, Serializable searchValue,
int maxResults);
}