001/*
002 * Copyright (c) 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 *
009 * Contributors:
010 *     Nuxeo - initial API and implementation
011 *
012 * $Id$
013 */
014
015package org.nuxeo.ecm.platform.audit.api;
016
017import java.util.Date;
018import java.util.List;
019import java.util.Map;
020
021/**
022 * Interface for reading data from the Audit service.
023 *
024 * @author tiry
025 */
026public interface AuditReader {
027
028    /**
029     * Returns the logs given a doc uuid.
030     *
031     * @param uuid the document uuid
032     * @return a list of log entries
033     */
034    List<LogEntry> getLogEntriesFor(String uuid);
035
036    List<LogEntry> getLogEntriesFor(String uuid, Map<String, FilterMapEntry> filterMap, boolean doDefaultSort);
037
038    /**
039     * Returns a given log entry given its id.
040     *
041     * @param id the log entry identifier
042     * @return a LogEntry instance
043     */
044    LogEntry getLogEntryByID(long id);
045
046    /**
047     * Returns the list of log entries.
048     * <p>
049     * Note we will use NXQL in the future when the search engine will index history.
050     *
051     * @see org.nuxeo.ecm.platform.audit.api.query.DateRangeQueryConstants
052     * @param eventIds the event ids.
053     * @param dateRange a preset date range.
054     * @return a list of log entries.
055     */
056    List<LogEntry> queryLogs(String[] eventIds, String dateRange);
057
058    /**
059     * Returns the batched list of log entries.
060     * <p>
061     * Note we will use NXQL in the future when the search engine will index history.
062     *
063     * @see org.nuxeo.ecm.platform.audit.api.query.DateRangeQueryConstants
064     * @param eventIds the event ids.
065     * @param dateRange a preset date range.
066     * @param category add filter on events category
067     * @param path add filter on document path
068     * @param pageNb page number (ignore if <=1)
069     * @param pageSize number of results per page
070     * @return a list of log entries.
071     */
072    List<LogEntry> queryLogsByPage(String[] eventIds, String dateRange, String category, String path, int pageNb,
073            int pageSize);
074
075    List<LogEntry> queryLogsByPage(String[] eventIds, String dateRange, String[] category, String path, int pageNb,
076            int pageSize);
077
078    /**
079     * Returns the batched list of log entries.
080     * <p>
081     * Note we will use NXQL in the future when the search engine will index history.
082     *
083     * @see org.nuxeo.ecm.platform.audit.api.query.DateRangeQueryConstants
084     * @param eventIds the event ids.
085     * @param limit filter events by date from limit to now
086     * @param category add filter on events category
087     * @param path add filter on document path
088     * @param pageNb page number (ignore if <=1)
089     * @param pageSize number of results per page
090     * @return a list of log entries.
091     */
092    List<LogEntry> queryLogsByPage(String[] eventIds, Date limit, String category, String path, int pageNb, int pageSize);
093
094    List<LogEntry> queryLogsByPage(String[] eventIds, Date limit, String[] category, String path, int pageNb,
095            int pageSize);
096
097    /**
098     * Returns a batched list of log entries. WhereClause is a native where clause for the backend: here EJBQL 3.0 must
099     * be used if implementation of audit backend is JPA (< 7.3 or audit.elasticsearch.enabled=false) and JSON if
100     * implementation is Elasticsearch.
101     */
102    List<LogEntry> nativeQueryLogs(String whereClause, int pageNb, int pageSize);
103
104    /**
105     * Returns a batched list of entries. query string is a native query clause for the backend : here EJBQL 3.0 must be
106     * used if implementation of audit backend is JPA (< 7.3 or audit.elasticsearch.enabled=false) and JSON if
107     * implementation is Elasticsearch.
108     */
109    List<?> nativeQuery(String query, int pageNb, int pageSize);
110
111    /**
112     * Returns a batched list of entries.
113     *
114     * @param query a JPA query language query if implementation of audit backend is JPA (< 7.3 or
115     *            audit.elasticsearch.enabled=false) and JSON if implementation is Elasticsearch
116     * @param params parameters for the query
117     * @param pageNb the page number (starts at 1)
118     * @param pageSize the number of results per page
119     */
120    List<?> nativeQuery(String query, Map<String, Object> params, int pageNb, int pageSize);
121
122}