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