001/*
002 * (C) Copyright 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Nuxeo - initial API and implementation
018 *
019 * $Id$
020 */
021
022package org.nuxeo.ecm.platform.audit.api;
023
024import java.util.Date;
025import java.util.List;
026import java.util.Map;
027
028/**
029 * Interface for reading data from the Audit service.
030 *
031 * @author tiry
032 */
033public interface AuditReader {
034
035    /**
036     * Returns the logs given a doc uuid and a repository id.
037     *
038     * @param uuid the document uuid
039     * @param repositoryId the repository id
040     * @return a list of log entries
041     * @since 8.4
042     */
043    List<LogEntry> getLogEntriesFor(String uuid, String repositoryId);
044
045    /**
046     * Returns the logs given a doc uuid.
047     *
048     * @param uuid the document uuid
049     * @return a list of log entries
050     * @deprecated since 8.4, use {@link (org.nuxeo.ecm.platform.audit.api.AuditReader.getLogEntriesFor(String,
051     *             String))} instead.
052     */
053    @Deprecated
054    List<LogEntry> getLogEntriesFor(String uuid);
055
056    /**
057     * Returns the logs given a doc uuid, a map of filters and a default sort.
058     *
059     * @param uuid the document uuid
060     * @param filterMap the map of filters to apply
061     * @param doDefaultSort the default sort to set
062     * @return a list of log entries
063     */
064    List<LogEntry> getLogEntriesFor(String uuid, Map<String, FilterMapEntry> filterMap, boolean doDefaultSort);
065
066    /**
067     * Returns a given log entry given its id.
068     *
069     * @param id the log entry identifier
070     * @return a LogEntry instance
071     */
072    LogEntry getLogEntryByID(long id);
073
074    /**
075     * Returns the list of log entries.
076     * <p>
077     * Note we will use NXQL in the future when the search engine will index history.
078     *
079     * @see org.nuxeo.ecm.platform.audit.api.query.DateRangeQueryConstants
080     * @param eventIds the event ids.
081     * @param dateRange a preset date range.
082     * @return a list of log entries.
083     */
084    List<LogEntry> queryLogs(String[] eventIds, String dateRange);
085
086    /**
087     * Returns the batched list of log entries.
088     * <p>
089     * Note we will use NXQL in the future when the search engine will index history.
090     *
091     * @see org.nuxeo.ecm.platform.audit.api.query.DateRangeQueryConstants
092     * @param eventIds the event ids.
093     * @param dateRange a preset date range.
094     * @param category add filter on events category
095     * @param path add filter on document path
096     * @param pageNb page number (ignore if <=1)
097     * @param pageSize number of results per page
098     * @return a list of log entries.
099     */
100    List<LogEntry> queryLogsByPage(String[] eventIds, String dateRange, String category, String path, int pageNb,
101            int pageSize);
102
103    List<LogEntry> queryLogsByPage(String[] eventIds, String dateRange, String[] category, String path, int pageNb,
104            int pageSize);
105
106    /**
107     * Returns the batched list of log entries.
108     * <p>
109     * Note we will use NXQL in the future when the search engine will index history.
110     *
111     * @see org.nuxeo.ecm.platform.audit.api.query.DateRangeQueryConstants
112     * @param eventIds the event ids.
113     * @param limit filter events by date from limit to now
114     * @param category add filter on events category
115     * @param path add filter on document path
116     * @param pageNb page number (ignore if <=1)
117     * @param pageSize number of results per page
118     * @return a list of log entries.
119     */
120    List<LogEntry> queryLogsByPage(String[] eventIds, Date limit, String category, String path, int pageNb,
121            int pageSize);
122
123    List<LogEntry> queryLogsByPage(String[] eventIds, Date limit, String[] category, String path, int pageNb,
124            int pageSize);
125
126    /**
127     * Returns a batched list of log entries. WhereClause is a native where clause for the backend: here EJBQL 3.0 must
128     * be used if implementation of audit backend is JPA (< 7.3 or audit.elasticsearch.enabled=false) and JSON if
129     * implementation is Elasticsearch.
130     */
131    List<LogEntry> nativeQueryLogs(String whereClause, int pageNb, int pageSize);
132
133    /**
134     * Returns a batched list of entries. query string is a native query clause for the backend : here EJBQL 3.0 must be
135     * used if implementation of audit backend is JPA (< 7.3 or audit.elasticsearch.enabled=false) and JSON if
136     * implementation is Elasticsearch.
137     */
138    List<?> nativeQuery(String query, int pageNb, int pageSize);
139
140    /**
141     * Returns a batched list of entries.
142     *
143     * @param query a JPA query language query if implementation of audit backend is JPA (< 7.3 or
144     *            audit.elasticsearch.enabled=false) and JSON if implementation is Elasticsearch
145     * @param params parameters for the query
146     * @param pageNb the page number (starts at 1)
147     * @param pageSize the number of results per page
148     */
149    List<?> nativeQuery(String query, Map<String, Object> params, int pageNb, int pageSize);
150
151}