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}