001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2002-2006, GeoTools Project Managment Committee (PMC)
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation;
009: * version 2.1 of the License.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: */
016: package org.geotools.data;
017:
018: import java.io.IOException;
019: import java.util.Set;
020: import org.opengis.filter.Filter;
021:
022: /**
023: * Provides Feature based locking.
024: *
025: * <p>
026: * Features from individual shapefiles, database tables, etc. can be protected
027: * or reserved from modification through this interface.
028: * </p>
029: * <p>
030: * To use please cast your FeatureSource to this interface.
031: * <pre><code>
032: * FeatureSource source = dataStore.getFeatureSource("roads");
033: * if( source instanceof FeatureLocking ) {
034: * FeatureLocking locking = (FeatureLocking) source;
035: * ...
036: * }
037: *
038: * @author Jody Garnett, Refractions Research, Inc.
039: * @author Ray Gallagher
040: * @author Rob Hranac, TOPP
041: * @author Chris Holmes, TOPP
042: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/api/src/main/java/org/geotools/data/FeatureLocking.java $
043: * @version $Id: FeatureLocking.java 22600 2006-11-04 09:37:58Z jgarnett $
044: */
045: public interface FeatureLocking extends FeatureStore {
046: /**
047: * All locking operations will operate against the provided
048: * <code>lock</code>.
049: *
050: * <p>
051: * This in in keeping with the stateful spirit of DataSource in which
052: * operations are against the "current" transaction. If a FeatureLock is
053: * not provided lock operations will only be applicable for the current
054: * transaction (they will expire on the next commit or rollback).
055: * </p>
056: *
057: * <p>
058: * That is lockFeatures() operations will:
059: * </p>
060: *
061: * <ul>
062: * <li>
063: * Be recorded against the provided FeatureLock.
064: * </li>
065: * <li>
066: * Be recorded against the current transaction if no FeatureLock is
067: * provided.
068: * </li>
069: * </ul>
070: *
071: * <p>
072: * Calling this method with <code>setFeatureLock( FeatureLock.TRANSACTION
073: * )</code> will revert to per transaction operation.
074: * </p>
075: *
076: * <p>
077: * This design allows for the following:
078: * </p>
079: *
080: * <ul>
081: * <li>
082: * cross DataSource FeatureLock usage
083: * </li>
084: * <li>
085: * not having pass in the same FeatureLock object multiple times
086: * </li>
087: * </ul>
088: *
089: * @param lock DOCUMENT ME!
090: */
091: void setFeatureLock(FeatureLock lock);
092:
093: /**
094: * FeatureLock features described by Query.
095: *
096: * <p>
097: * To implement WFS parcial Locking retrieve your features with a query
098: * operation first before trying to lock them individually. If you are not
099: * into WFS please don't ask what parcial locking is.
100: * </p>
101: *
102: * @param query Query describing the features to lock
103: *
104: * @return Number of features locked
105: *
106: * @throws IOException Thrown if anything goes wrong
107: */
108: int lockFeatures(Query query) throws IOException;
109:
110: /**
111: * FeatureLock features described by Filter.
112: *
113: * <p>
114: * To implement WFS parcial Locking retrieve your features with a query
115: * operation first before trying to lock them individually. If you are not
116: * into WFS please don't ask what parcial locking is.
117: * </p>
118: *
119: * @param filter Filter describing the features to lock
120: *
121: * @return Number of features locked
122: *
123: * @throws IOException Thrown if anything goes wrong
124: */
125: int lockFeatures(Filter filter) throws IOException;
126:
127: /**
128: * FeatureLock all Features.
129: *
130: * <p>
131: * The method does not prevent addFeatures() from being used (we could add
132: * a lockDataSource() method if this functionality is required.
133: * </p>
134: *
135: * @return Number of Features locked by this opperation
136: *
137: * @throws IOException
138: */
139: int lockFeatures() throws IOException;
140:
141: /**
142: * Unlocks all Features.
143: *
144: * <p>
145: * Authorization must be provided prior before calling this method.
146: * </p>
147: * <pre><code>
148: * <b>void</b> releaseLock( String lockId, LockingDataSource ds ){
149: * ds.setAuthorization( "LOCK534" );
150: * ds.unLockFeatures();
151: * }
152: * </code></pre>
153: *
154: * @throws IOException
155: */
156: void unLockFeatures() throws IOException;
157:
158: /**
159: * Unlock Features denoted by provided filter.
160: *
161: * <p>
162: * Authorization must be provided prior before calling this method.
163: * </p>
164: *
165: * @param filter
166: *
167: * @throws IOException
168: */
169: void unLockFeatures(Filter filter) throws IOException;
170:
171: /**
172: * Unlock Features denoted by provided query.
173: *
174: * <p>
175: * Authorization must be provided prior before calling this method.
176: * </p>
177: *
178: * @param query Specifies fatures to unlock
179: *
180: * @throws IOException
181: */
182: void unLockFeatures(Query query) throws IOException;
183:
184: /**
185: * Idea for a response from a high-level lock( Query ) function.
186: */
187: public static class Response {
188: String authID;
189: Set locked;
190: Set notLocked;
191:
192: public Response(FeatureLock lock, Set lockedFids,
193: Set notLockedFids) {
194: authID = lock.getAuthorization();
195: locked = lockedFids;
196: notLocked = notLockedFids;
197: }
198:
199: public String getAuthorizationID() {
200: return authID;
201: }
202:
203: public Set getLockedFids() {
204: return locked;
205: }
206:
207: public Set getNotLockedFids() {
208: return notLocked;
209: }
210: }
211: }
|