001/*
002 * (C) Copyright 2006-2017 Nuxeo (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 *     Florent Guillaume
018 */
019package org.nuxeo.ecm.core.storage.sql;
020
021import java.io.Serializable;
022import java.util.Calendar;
023import java.util.Collection;
024import java.util.Map;
025import java.util.Set;
026
027import org.nuxeo.ecm.core.api.IterableQueryResult;
028import org.nuxeo.ecm.core.api.PartialList;
029import org.nuxeo.ecm.core.api.ScrollResult;
030import org.nuxeo.ecm.core.query.QueryFilter;
031
032/**
033 * A {@link Mapper} maps {@link Row}s to and from the database.
034 */
035public interface Mapper extends RowMapper {
036
037    /**
038     * Executes the given query and returns the first batch of results containing id of documents, next batch must be
039     * requested within the {@code keepAliveSeconds} delay.
040     *
041     * @since 8.4
042     */
043    ScrollResult<String> scroll(String query, int batchSize, int keepAliveSeconds);
044
045    /**
046     * Executes the given query and returns the first batch of results containing id of documents, next batch must be
047     * requested within the {@code keepAliveSeconds} delay.
048     *
049     * @since 10.3
050     */
051    ScrollResult<String> scroll(String query, QueryFilter queryFilter, int batchSize, int keepAliveSeconds);
052
053    /**
054     * Get the next batch of results containing id of documents, the {@code scrollId} is part of the previous
055     * {@link ScrollResult} response.
056     *
057     * @since 8.4
058     */
059    ScrollResult<String> scroll(String scrollId);
060
061    /**
062     * Identifiers assigned by a server to identify a client mapper and its repository.
063     */
064    final class Identification implements Serializable {
065
066        private static final long serialVersionUID = 1L;
067
068        public final String repositoryId;
069
070        public final String mapperId;
071
072        public Identification(String repositoryId, String mapperId) {
073            this.repositoryId = repositoryId;
074            this.mapperId = mapperId;
075        }
076
077        @Override
078        public String toString() {
079            return getClass().getSimpleName() + '(' + repositoryId + ',' + mapperId + ')';
080        }
081
082    }
083
084    /**
085     * Returns the repository id and mapper id assigned.
086     * <p>
087     * This is used in remote stateless mode to be able to identify to which mapper an incoming connection is targeted,
088     * and from which repository instance.
089     *
090     * @return the repository and mapper identification
091     */
092    Identification getIdentification();
093
094    // used for reflection
095    String GET_IDENTIFICATION = "getIdentification";
096
097    void close();
098
099    // used for reflection
100    String CLOSE = "close";
101
102    // TODO
103    int getTableSize(String tableName);
104
105    /*
106     * ========== Methods returning non-Rows ==========
107     */
108
109    /*
110     * ----- Root -----
111     */
112
113    /**
114     * Gets the root id for a given repository, if registered.
115     *
116     * @param repositoryId the repository id
117     * @return the root id, or null if not found
118     */
119    Serializable getRootId(String repositoryId);
120
121    /**
122     * Records the newly generated root id for a given repository.
123     *
124     * @param repositoryId the repository id, usually 0
125     * @param id the root id
126     */
127    void setRootId(Serializable repositoryId, Serializable id);
128
129    /*
130     * ----- Query -----
131     */
132
133    /**
134     * Makes a NXQL query to the database.
135     *
136     * @param query the query
137     * @param queryType the query type
138     * @param queryFilter the query filter
139     * @param countTotal if {@code true}, count the total size without limit/offset
140     * @return the list of matching document ids
141     */
142    PartialList<Serializable> query(String query, String queryType, QueryFilter queryFilter, boolean countTotal);
143
144    /**
145     * Makes a NXQL query to the database.
146     *
147     * @param query the query
148     * @param queryType the query type
149     * @param queryFilter the query filter
150     * @param countUpTo if {@code -1}, count the total size without offset/limit.<br>
151     *            If {@code 0}, don't count the total size.<br>
152     *            If {@code n}, count the total number if there are less than n documents otherwise set the size to
153     *            {@code -1}.
154     * @return the list of matching document ids
155     * @since 5.6
156     */
157    PartialList<Serializable> query(String query, String queryType, QueryFilter queryFilter, long countUpTo);
158
159    /**
160     * Makes a query to the database and returns an iterable (which must be closed when done).
161     *
162     * @param query the query
163     * @param queryType the query type
164     * @param queryFilter the query filter
165     * @param distinctDocuments if {@code true} then a maximum of one row per document will be returned
166     * @param params optional query-type-dependent parameters
167     * @return an iterable, which <b>must</b> be closed when done
168     */
169    // queryFilter used for principals and permissions
170    IterableQueryResult queryAndFetch(String query, String queryType, QueryFilter queryFilter,
171            boolean distinctDocuments, Object... params);
172
173    /**
174     * Makes a query to the database.
175     *
176     * @param query the query
177     * @param queryType the query type
178     * @param queryFilter the query filter
179     * @param distinctDocuments if {@code true} then a maximum of one row per document will be returned
180     * @param countUpTo if {@code -1}, also count the total size without offset/limit.<br>
181     *            If {@code 0}, don't count the total size.<br>
182     *            If {@code n}, count the total number if there are less than n documents otherwise set the size to
183     *            {@code -1}.
184     * @param params optional query-type-dependent parameters
185     * @return a projection
186     * @since 7.10-HF-25, 8.10-HF06, 9.2
187     */
188    PartialList<Map<String,Serializable>> queryProjection(String query, String queryType, QueryFilter queryFilter, boolean distinctDocuments,
189            long countUpTo, Object... params);
190
191    /**
192     * Gets the ids for all the ancestors of the given row ids.
193     *
194     * @param ids the ids
195     * @return the set of ancestor ids
196     */
197    Set<Serializable> getAncestorsIds(Collection<Serializable> ids);
198
199    /*
200     * ----- ACLs -----
201     */
202
203    void updateReadAcls();
204
205    void rebuildReadAcls();
206
207    /*
208     * ----- Clustering -----
209     */
210
211    int getClusterNodeIdType();
212
213    /**
214     * Informs the cluster that this node exists.
215     */
216    void createClusterNode(Serializable nodeId);
217
218    /**
219     * Removes this node from the cluster.
220     */
221    void removeClusterNode(Serializable nodeId);
222
223    /**
224     * Inserts the invalidation rows for the other cluster nodes.
225     */
226    void insertClusterInvalidations(Serializable nodeId, VCSInvalidations invalidations);
227
228    /**
229     * Gets the invalidations from other cluster nodes.
230     */
231    VCSInvalidations getClusterInvalidations(Serializable nodeId);
232
233    /**
234     * Marks the binaries in use by passing them to the binary manager(s)'s GC mark() method.
235     */
236    void markReferencedBinaries();
237
238    /**
239     * Cleans up (hard-delete) any rows that have been soft-deleted in the database.
240     *
241     * @param max the maximum number of rows to delete at a time
242     * @param beforeTime the maximum deletion time of the rows to delete
243     * @return the number of rows deleted
244     */
245    int cleanupDeletedRows(int max, Calendar beforeTime);
246
247}