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}