001/*
002 * (C) Copyright 2014-2016 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 */
019package org.nuxeo.ecm.core.storage.dbs;
020
021import java.io.Serializable;
022import java.util.List;
023import java.util.Map;
024import java.util.Set;
025
026import org.nuxeo.ecm.core.api.PartialList;
027import org.nuxeo.ecm.core.blob.BlobManager;
028import org.nuxeo.ecm.core.model.LockManager;
029import org.nuxeo.ecm.core.model.Repository;
030import org.nuxeo.ecm.core.query.sql.model.OrderByClause;
031import org.nuxeo.ecm.core.storage.FulltextConfiguration;
032import org.nuxeo.ecm.core.storage.State;
033import org.nuxeo.ecm.core.storage.State.StateDiff;
034
035/**
036 * Interface for a {@link Repository} for Document-Based Storage.
037 *
038 * @since 5.9.4
039 */
040public interface DBSRepository extends Repository, LockManager {
041
042    /**
043     * Gets the blob manager.
044     *
045     * @return the blob manager.
046     */
047    BlobManager getBlobManager();
048
049    /**
050     * Gets the fulltext configuration.
051     *
052     * @return the fulltext configuration
053     * @since 7.10-HF04, 8.1
054     */
055    FulltextConfiguration getFulltextConfiguration();
056
057    /**
058     * Checks if fulltext indexing is disabled.
059     *
060     * @return {@code true} if fulltext indexing is disabled, {@code false} if it is enabled
061     * @since 7.1, 6.0-HF02
062     */
063    boolean isFulltextDisabled();
064
065    /**
066     * Gets the root id.
067     *
068     * @return the root id.
069     */
070    String getRootId();
071
072    /**
073     * Generates a new id for a document.
074     *
075     * @return the new id
076     */
077    String generateNewId();
078
079    /**
080     * Reads the state of a document.
081     *
082     * @param id the document id
083     * @return the document state, or {@code null} if not found
084     */
085    State readState(String id);
086
087    /**
088     * Reads the states of several documents.
089     * <p>
090     * The returned states may be in a different order than the ids.
091     *
092     * @param ids the document ids
093     * @return the document states, an element by be {@code null} if not found
094     */
095    List<State> readStates(List<String> ids);
096
097    /**
098     * Creates a document.
099     *
100     * @param state the document state
101     */
102    void createState(State state);
103
104    /**
105     * Creates documents.
106     *
107     * @param states the document states
108     */
109    default void createStates(List<State> states) {
110        states.forEach(this::createState);
111    }
112
113    /**
114     * Updates a document.
115     *
116     * @param id the document id
117     * @param diff the diff to apply
118     */
119    void updateState(String id, StateDiff diff);
120
121    /**
122     * Deletes a set of document.
123     *
124     * @param ids the document ids
125     */
126    void deleteStates(Set<String> ids);
127
128    /**
129     * Reads the state of a child document.
130     *
131     * @param parentId the parent document id
132     * @param name the name of the child
133     * @param ignored a set of document ids that should not be considered
134     * @return the state of the child document, or {@code null} if not found
135     */
136    State readChildState(String parentId, String name, Set<String> ignored);
137
138    /**
139     * Checks if a document has a child with the given name
140     *
141     * @param parentId the parent document id
142     * @param name the name of the child
143     * @param ignored a set of document ids that should not be considered
144     * @return {@code true} if the child exists, {@code false} if not
145     */
146    boolean hasChild(String parentId, String name, Set<String> ignored);
147
148    /**
149     * Queries the repository for documents having key = value.
150     *
151     * @param key the key
152     * @param value the value
153     * @param ignored a set of document ids that should not be considered
154     * @return the document states matching the query
155     */
156    List<State> queryKeyValue(String key, Object value, Set<String> ignored);
157
158    /**
159     * Queries the repository for documents having key1 = value1 and key2 = value2.
160     *
161     * @param key1 the first key
162     * @param value1 the first value
163     * @param key2 the second key
164     * @param value2 the second value
165     * @param ignored a set of document ids that should not be considered
166     * @return the document states matching the query
167     */
168    List<State> queryKeyValue(String key1, Object value1, String key2, Object value2, Set<String> ignored);
169
170    /**
171     * Queries the repository for document ids having value in key (an array).
172     *
173     * @param key the key
174     * @param value the value
175     * @param ids the set which receives the documents ids
176     * @param proxyTargets returns a map of proxy to target among the documents found
177     * @param targetProxies returns a map of target to proxies among the document found
178     */
179    void queryKeyValueArray(String key, Object value, Set<String> ids, Map<String, String> proxyTargets,
180            Map<String, Object[]> targetProxies);
181
182    /**
183     * Queries the repository to check if there are documents having key = value.
184     *
185     * @param key the key
186     * @param value the value
187     * @param ignored a set of document ids that should not be considered
188     * @return {@code true} if the query matches at least one document, {@code false} if the query matches nothing
189     */
190    boolean queryKeyValuePresence(String key, String value, Set<String> ignored);
191
192    /**
193     * Queries the repository for documents matching a NXQL query, and returns a projection of the documents.
194     *
195     * @param evaluator the map-based evaluator for the query
196     * @param orderByClause an ORDER BY clause
197     * @param distinctDocuments {@code true} if the projection should return a maximum of one row per document
198     * @param limit the limit on the number of documents to return
199     * @param offset the offset in the list of documents to return
200     * @param countUpTo if {@code -1}, count the total size without offset/limit.<br>
201     *            If {@code 0}, don't count the total size, set it to {@code -1} .<br>
202     *            If {@code n}, count the total number if there are less than n documents otherwise set the total size
203     *            to {@code -2}.
204     * @return a partial list of maps containing the NXQL projections requested, and the total size according to
205     *         countUpTo
206     */
207    PartialList<Map<String, Serializable>> queryAndFetch(DBSExpressionEvaluator evaluator, OrderByClause orderByClause,
208            boolean distinctDocuments, int limit, int offset, int countUpTo);
209
210    /**
211     * Gets the lock manager for this repository.
212     *
213     * @return the lock manager
214     * @since 7.4
215     */
216    LockManager getLockManager();
217
218}