001 /*
002 * Repository.java
003 * Copyright (c) 1998-2008, The University of Sheffield.
004 *
005 * This code is from the GATE project (http://gate.ac.uk/) and is free
006 * software licenced under the GNU General Public License version 3. It is
007 * distributed without any warranty. For more details see COPYING.txt in the
008 * top level directory (or at http://gatewiki.sf.net/COPYING.txt).
009 *
010 * Hamish Cunningham 27/Aug/2005
011 */
012
013 package gate.versioning.cmdline;
014 import java.io.*;
015 import gate.util.*;
016
017 /**
018 * This is the main entry point for the version control package. See also the
019 * {@link gate.versioning.cmdline package overview}. The name of this interface
020 * is a little misleading: it doesn't really model version control
021 * repositories, but version control <b>commands</b>. In a perfect world it
022 * would be renamed.
023 * <p>
024 * Version control repository interface. Implementors are intended to use
025 * bean-type parameterisation and initialisation. The lifecycle is:
026 * <ul>
027 * <li>
028 * use a no-arg constructor to create an object
029 * <li>
030 * set required parameters (e.g. root or URL of the repository; working
031 * directory for repository access commands)
032 * <li>
033 * call {@link #init} which will validate the parameters and put the object in
034 * a usable state
035 * <li>
036 * call other methods as required
037 * </ul>
038 * An exception to the rule of calling {@link #init} before other methods is
039 * {@link #create}, which can be called on an unitialised object (so that we
040 * can create repositories without having an existing one).
041 * <p>
042 * Implementors are expected to execute the command-line repository program
043 * to do the work specified by this API. The anticipated uses are with CVS
044 * and SVN. The API is kept close to the underlying version control systems,
045 * so, for example, to delete a file first delete the actual file from disk,
046 * then call {@link #delete}, then call {@link #checkin} to commit the
047 * deletion.
048 *
049 * A Repository object may also be obtained from
050 * {@link AbstractRepository#getRepository(java.lang.String)}.
051 */
052 public interface Repository {
053
054 /**
055 * Validate parameters.
056 */
057 public void init() throws GateException;
058
059 /**
060 * Name of the repository command to execute (e.g. cvs, svn). This is
061 * mainly useful for implementors of this interface.
062 */
063 abstract public String getCommandName();
064
065
066 /** The root / URL of the repository */
067 public void setRoot(String root);
068
069 /** The root / URL of the repository */
070 public String getRoot();
071
072 /** The working directory for repository actions */
073 public void setWorkingDir(File workingDir);
074
075 /**
076 * Check out a file, directory or module.
077 * @param fileName the file or directory to work on (should be relative
078 * to the repository's working directory, and use "/" as a path separator).
079 * @return boolean representing success or failure.
080 */
081 public boolean checkout(String fileName);
082
083 /**
084 * Commit changes. A default message is used.
085 * @param fileName the file or directory to work on (should be relative
086 * to the repository's working directory, and use "/" as a path separator).
087 * @return boolean representing success or failure.
088 */
089 public boolean checkin(String fileName);
090
091 /**
092 * Commit changes.
093 * @param fileName the file or directory to work on (should be relative
094 * to the repository's working directory, and use "/" as a path separator).
095 * @param message a commit message.
096 * @return boolean representing success or failure.
097 */
098 public boolean checkin(String fileName, String message);
099
100 /**
101 * Update.
102 * @param fileName the file or directory to work on (should be relative
103 * to the repository's working directory, and use "/" as a path separator).
104 * @return boolean representing success or failure.
105 */
106 public boolean update(String fileName);
107
108 /**
109 * Status.
110 * @param fileName the file or directory to work on (should be relative
111 * to the repository's working directory, and use "/" as a path separator).
112 * @return String giving status output.
113 */
114 public String status(String fileName);
115
116 /**
117 * Use the repository's status command to figure out if the file has been
118 * locally modified.
119 * @param fileName the file or directory to work on (should be relative
120 * to the repository's working directory, and use "/" as a path separator).
121 * @return boolean giving status indication.
122 */
123 public boolean isModified(String fileName);
124
125 /**
126 * Use the repository's status command to figure out if the file is
127 * out-of-date.
128 * @param fileName the file or directory to work on (should be relative
129 * to the repository's working directory, and use "/" as a path separator).
130 * @return boolean giving status indication.
131 */
132 public boolean isOutOfDate(String fileName);
133
134 /**
135 * Use the repository's status command to figure out if the file is
136 * unknown. This only works when you're looking for a file relative
137 * to a working copy - to check for existence use {@link #exists}.
138 * @param fileName the file or directory to work on (should be relative
139 * to the repository's working directory, and use "/" as a path separator).
140 * @return boolean giving status indication.
141 */
142 public boolean isUnknown(String fileName);
143
144 /**
145 * Check for the existence of a module (i.e. top-level directory).
146 * @param moduleName directory to look for.
147 * @return boolean giving status indication.
148 */
149 public boolean exists(String moduleName);
150
151 /**
152 * Delete from the repository.
153 * @param fileName the file or directory to work on (should be relative
154 * to the repository's working directory, and use "/" as a path separator).
155 * @return boolean representing success or failure.
156 */
157 public boolean delete(String fileName);
158
159 /**
160 * Add to the repository.
161 * @param fileName the file or directory to work on (should be relative
162 * to the repository's working directory, and use "/" as a path separator).
163 * @return boolean representing success or failure.
164 */
165 public boolean add(String fileName);
166
167 /**
168 * Get the difference with the repository version.
169 * @param fileName the file or directory to work on (should be relative
170 * to the repository's working directory, and use "/" as a path separator).
171 * @return a string containing the difference, or "" for no difference, or
172 * null for error.
173 */
174 public String diff(String fileName);
175
176 /**
177 * Create a new repository filetree (i.e. not a new object but a new
178 * database/filesystem on disk).
179 * @param dirName the directory to work on, which will be created
180 * (should be an absolute path).
181 * @return boolean representing success or failure.
182 */
183 public boolean create(String dirName) throws GateException;
184
185 /**
186 * Import a directory.
187 * @param dirName the directory to import (this must exist).
188 * @return boolean representing success or failure.
189 * @throws GateException when the directory doesn't exist.
190 */
191 public boolean importDir(String dirName) throws GateException;
192
193 /** Get a string containing the stdout from the command execution. */
194 public String getCommandStdout();
195
196 /** Get a string containing the stderr from the command execution. */
197 public String getCommandStderr();
198
199 /**
200 * Get a string containing the stdout and stderr from the command
201 * execution.
202 */
203 public String getCommandOutput();
204
205 } // Repository
|