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.SVNException;
016: import org.tmatesoft.svn.core.SVNURL;
017:
018: /**
019: * The <b>ISVNReporter</b> interface provides methods to describe
020: * the state of local paths in order to get the differences in revisions
021: * between those local paths and what is actually in the repository.
022: *
023: * <p>
024: * <b>ISVNReporter</b> objects are used by <b>ISVNReporterBaton</b>
025: * implementations, provided by callers of the <b>SVNRepository</b>'s update,
026: * switch, status, diff operations.
027: *
028: * <p>
029: * Paths for report calls are relative to the target of the operation (that is the
030: * directory where the command was run). Report calls must be made in depth-first
031: * order: parents before children, all children of a parent before any
032: * siblings of the parent. The first report call must be a
033: * {@link #setPath(String, String, long, boolean) setPath()} with a path argument of
034: * <span class="javastring">""</span> and a valid revision. If the target of the operation
035: * is locally deleted or missing, use the root path's revision. If the target of the operation is
036: * deleted or switched relative to the root path, follow up the initial
037: * {@link #setPath(String, String, long, boolean) setPath()} call with a
038: * {@link #linkPath(SVNURL, String, String, long, boolean) linkPath()}
039: * or {@link #deletePath(String) deletePath()} call with a path argument of
040: * <span class="javastring">""</span> to
041: * indicate that. In no other case may there be two report
042: * descriptions for the same path. If the target of the operation is
043: * a locally added file or directory (which previously did not exist),
044: * it may be reported as having revision 0 or as having the parent
045: * directory's revision.
046: *
047: * For more information on using reporters, please, read these on-line article:
048: * <a href="http://svnkit.com/kb/dev-guide-update-operation.html">Using ISVNReporter/ISVNEditor in update-related operations</a>
049: *
050: * @version 1.1.1
051: * @author TMate Software Ltd.
052: * @see ISVNReporterBaton
053: * @see SVNRepository
054: * @see <a target="_top" href="http://svnkit.com/kb/examples/">Examples</a>
055: */
056: public interface ISVNReporter {
057:
058: /**
059: * <p>
060: * Describes a local path as being at a particular revision.
061: *
062: * <p>
063: * If <code>startEmpty</code> is <span class="javakeyword">true</span> and the
064: * <code>path</code> is a directory, an implementor should assume the
065: * directory has no entries or properties (used in checkouts and aborted updates).
066: *
067: * <p>
068: * A next call to this method will "override" any previous <code>setPath()</code> calls made on parent
069: * paths. The <code>path</code> is relative to the repository location specified for an
070: * <b>SVNRepository</b> driver.
071: *
072: * @param path a local item's path
073: * @param lockToken if not <span class="javakeyword">null</span>, it is a lock token
074: * for the <code>path</code>
075: * @param revision the local item's revision number
076: * @param startEmpty if <span class="javakeyword">true</span> and if the <code>path</code> is a
077: * directory, then means there're no entries yet
078: * @throws SVNException
079: *
080: */
081: public void setPath(String path, String lockToken, long revision,
082: boolean startEmpty) throws SVNException;
083:
084: /**
085: *
086: * Describes a working copy <code>path</code> as deleted or missing.
087: *
088: * @param path a path relative to the root of the report
089: * @throws SVNException
090: */
091: public void deletePath(String path) throws SVNException;
092:
093: /**
094: * <p>
095: * Describes a local path as being at a particular revision
096: * to switch the path to a different repository location.
097: *
098: * Like {@link #setPath(String, String, long, boolean) setPath()}, but differs in
099: * that the local item's <code>path</code> (relative to the root
100: * of the report driver) isn't a reflection of the path in the repository,
101: * but is instead a reflection of a different repository path at a
102: * <code>revision</code>.
103: *
104: * <p>
105: * If <code>startEmpty</code> is set and the <code>path</code> is a directory,
106: * the implementor should assume the directory has no entries or properties.
107: *
108: * @param url a new repository location to switch to
109: * @param path the local item's path
110: * @param lockToken if not <span class="javakeyword">null</span>, it is a lock token
111: * for the <code>path</code>
112: * @param revison the local item's revision number
113: * @param startEmpty if <span class="javakeyword">true</span> and if the <code>path</code> is a
114: * directory, then means there're no entries yet
115: * @throws SVNException
116: */
117:
118: public void linkPath(SVNURL url, String path, String lockToken,
119: long revison, boolean startEmpty) throws SVNException;
120:
121: /**
122: * Finalizes the report. Must be called when having traversed a local
123: * tree of paths.
124: *
125: * <p>
126: * Any directories or files not explicitly set (described)
127: * are assumed to be at the baseline revision.
128: *
129: * @throws SVNException
130: */
131: public void finishReport() throws SVNException;
132:
133: /**
134: * Aborts the current running report due to errors occured.
135: *
136: * <p>
137: * If an error occurs during a report, call this method
138: * to abort the reporter correctly.
139: *
140: * @throws SVNException
141: */
142: public void abortReport() throws SVNException;
143: }
|