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