001: /*
002: * ====================================================================
003: * Copyright (c) 2004-2008 TMate Software Ltd. All rights reserved.
004: *
005: * This software is licensed as described in the file COPYING, which
006: * you should have received as part of this distribution. The terms
007: * are also available at http://svnkit.com/license.html
008: * If newer versions of this license are posted there, you may use a
009: * newer version instead, at your option.
010: * ====================================================================
011: */
012:
013: package org.tmatesoft.svn.core.io;
014:
015: import org.tmatesoft.svn.core.SVNCommitInfo;
016: import org.tmatesoft.svn.core.SVNException;
017:
018: /**
019: * The <b>ISVNEditor</b> interface is used by <b>SVNRepository</b> to
020: * update versioned files/dirs, check out files/dirs from a repository,
021: * commit changes to a repository, take status of files/dirs,
022: * get differences between files.
023: *
024: * <p>
025: * When used for updating (checking out, getting differences or status), an
026: * implementor should provide its own appropriate implementation of the
027: * <b>ISVNEditor</b> interface along with a reporter baton (<b>ISVNReposrterBaton</b>)
028: * to a corresponding method of an <b>SVNRepository</b> driver. Reporter baton
029: * will be used to describe the state of local dirs/files - their current revisions,
030: * whether a file/dir is deleted or switched. An editor is invoked after the reporter
031: * baton finishes its work. It is used to "edit" the state of files/dirs, where
032: * "edit" may mean anything: applying changes in updating, switching, checking out (what
033: * really changes the state), or handling changes in getting status or differences (what is
034: * only used to inform about, show, separately store changes, and so on). The concrete behaviour
035: * of the editor is implemented by the provider of that editor.
036: *
037: * <p>
038: * The other kind of using <b>ISVNEditor</b> is committing changes to a repository.
039: * Here an editor is given to a caller, and the caller himself describes the changes
040: * of local files/dirs. All that collected info is then committed in a single transaction
041: * when a caller invokes the {@link #closeEdit()} method of the editor.
042: *
043: * For more information on using editors, please, read these on-line articles:
044: * <ul>
045: * <li><a href="http://svnkit.com/kb/dev-guide-update-operation.html">Using ISVNReporter/ISVNEditor in update-related operations</a>
046: * <li><a href="http://svnkit.com/kb/dev-guide-commit-operation.html">Using ISVNEditor in commit operations</a>
047: * </ul>
048: *
049: * @version 1.1.1
050: * @author TMate Software Ltd.
051: * @see ISVNReporterBaton
052: * @see <a target="_top" href="http://svnkit.com/kb/examples/">Examples</a>
053: */
054: public interface ISVNEditor extends ISVNDeltaConsumer {
055: /**
056: * Sets the target revision the operation is running for. For example,
057: * the target revision to which an update is running.
058: *
059: * @param revision a revision number
060: * @throws SVNException
061: */
062: public void targetRevision(long revision) throws SVNException;
063:
064: /**
065: * Opens the root directory on which the operation was invoked. All
066: * property changes as well as entries adding/deletion will be applied to this
067: * root directory.
068: * When coming back up to this root (after traversing the entire tree) you
069: * should close the root by calling {@link #closeDir()}.
070: *
071: * @param revision the revision number of the root directory
072: * @throws SVNException
073: */
074: public void openRoot(long revision) throws SVNException;
075:
076: /**
077: * Deletes an entry.
078: * <p>
079: * In a commit - deletes an entry from a repository. In an update -
080: * deletes an entry locally (since it has been deleted in the repository).
081: * In a status - informs that an entry has been deleted.
082: *
083: * @param path an entry path relative to the root
084: * directory opened by {@link #openRoot(long) openRoot()}
085: * @param revision the revision number of <code>path</code>
086: * @throws SVNException
087: */
088: public void deleteEntry(String path, long revision)
089: throws SVNException;
090:
091: /**
092: * Indicates that a path is present as a subdirectory in the edit source,
093: * but can not be conveyed to the edit consumer (perhaps because of
094: * authorization restrictions).
095: *
096: * @param path a dir path relative to the root
097: * directory opened by {@link #openRoot(long) openRoot()}
098: * @throws SVNException
099: */
100: public void absentDir(String path) throws SVNException;
101:
102: /**
103: * Indicates that a path is present as a file in the edit source,
104: * but can not be conveyed to the edit consumer (perhaps because of
105: * authorization restrictions).
106: *
107: * @param path a file path relative to the root
108: * directory opened by {@link #openRoot(long) openRoot()}
109: * @throws SVNException
110: */
111: public void absentFile(String path) throws SVNException;
112:
113: /**
114: * Adds a directory.
115: *
116: * <p>
117: * In a commit - adds a new directory to a repository. In an update - locally adds
118: * a directory that was added in the repository. In a status - informs about a new
119: * directory scheduled for addition.
120: *
121: * <p>
122: * If <code>copyFromPath</code> is not <span class="javakeyword">null</span> then it says
123: * that <code>path</code> is copied from <code>copyFromPath</code> located in
124: * <code>copyFromRevision</code>.
125: *
126: * @param path a directory path relative to the root
127: * directory opened by {@link #openRoot(long) openRoot()}
128: * @param copyFromPath an ancestor of the added directory
129: * @param copyFromRevision the revision of the ancestor
130: * @throws SVNException
131: */
132: public void addDir(String path, String copyFromPath,
133: long copyFromRevision) throws SVNException;
134:
135: /**
136: * Opens a directory. All property changes as well as entries
137: * adding/deletion can be applied to this directory.
138: *
139: * @param path a directory path relative to the root
140: * directory opened by {@link #openRoot(long) openRoot()}
141: * @param revision the revision of the directory
142: * @throws SVNException
143: */
144: public void openDir(String path, long revision) throws SVNException;
145:
146: /**
147: * Changes the value of a property of the currently "opened"/"added" directory.
148: *
149: * @param name the name of a property to be changed
150: * @param value new property value
151: * @throws SVNException
152: * @see #openDir(String, long)
153: */
154: public void changeDirProperty(String name, String value)
155: throws SVNException;
156:
157: /**
158: * Closes the currently opened directory fixing all changes of its
159: * properties and/or entries. Closing a directory picks up an editor
160: * to a parent directory.
161: *
162: * @throws SVNException
163: */
164: public void closeDir() throws SVNException;
165:
166: /**
167: * Adds a file.
168: *
169: * <p>
170: * In a commit - adds a new file to a repository. In an update - locally adds
171: * a file that was added in the repository. In a status - informs about a new
172: * file scheduled for addition.
173: *
174: * <p>
175: * If <code>copyFromPath</code> is not <span class="javakeyword">null</span> then it says
176: * that <code>path</code> is copied from <code>copyFromPath</code> located in
177: * <code>copyFromRevision</code>.
178: *
179: * @param path a file path relative to the root
180: * directory opened by {@link #openRoot(long) openRoot()}
181: * @param copyFromPath an ancestor of the added file
182: * @param copyFromRevision the revision of the ancestor
183: * @throws SVNException
184: */
185: public void addFile(String path, String copyFromPath,
186: long copyFromRevision) throws SVNException;
187:
188: /**
189: * Opens a file. After it's opened, apply delta to its contents or change the
190: * file properties.
191: *
192: * @param path a file path relative to the root
193: * directory opened by {@link #openRoot(long) openRoot()}
194: * @param revision the revision of the file
195: *
196: * @throws SVNException
197: */
198: public void openFile(String path, long revision)
199: throws SVNException;
200:
201: /**
202: * Changes the value of a property of an opened file.
203: *
204: * @param path a file path relative to the root
205: * directory opened by {@link #openRoot(long) openRoot()}
206: * @param name a file property name
207: * @param value a new value for the property
208: * @throws SVNException
209: */
210: public void changeFileProperty(String path, String name,
211: String value) throws SVNException;
212:
213: /**
214: * Closes the opened file fixing all properties and/or contents changes.
215: *
216: * @param path a file path relative to the root
217: * directory opened by {@link #openRoot(long) openRoot()}
218: * @param textChecksum an MD5 checksum for the modified file
219: * @throws SVNException if the calculated upon the actual changed contents
220: * checksum does not match the expected <code>textChecksum</code>
221: */
222: public void closeFile(String path, String textChecksum)
223: throws SVNException;
224:
225: /**
226: * Closes this editor finalizing the whole operation the editor
227: * was used for. In a commit - sends collected data to commit a transaction.
228: *
229: * @return a committed revision information
230: * @throws SVNException
231: */
232: public SVNCommitInfo closeEdit() throws SVNException;
233:
234: /**
235: * Aborts the current running editor due to errors occured.
236: *
237: * <p>
238: * If an exception is thrown from an editor's method, call this method
239: * to abort the editor.
240: *
241: * @throws SVNException
242: */
243: public void abortEdit() throws SVNException;
244: }
|