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}