1 /********************************************************************************
2 * $Id: Client.java 125 2008-07-10 20:32:42Z sjardine $
3 *
4 * Copyright 2005-2008 Steven Jardine, MJN Services, Inc. <steve@mjnservices.com>
5 *
6 * All rights reserved. This program and the accompanying materials are made
7 * available under the terms of the GNU Lesser Public License v2.1 which
8 * accompanies this distribution, and is available at
9 * http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
10 *
11 * For more information on the HylaFAX Fax Server please see
12 * HylaFAX - http://www.hylafax.org or
13 * Hylafax+ - http://hylafax.sourceforge.net
14 *
15 * Contributors:
16 * Steven Jardine - Initial API and implementation
17 ******************************************************************************/
18 package gnu.hylafax;
19
20 import gnu.inet.ftp.ConnectionEventSource;
21 import gnu.inet.ftp.ServerResponseException;
22 import gnu.inet.ftp.TransferEventSource;
23
24 import java.io.FileNotFoundException;
25 import java.io.IOException;
26 import java.io.InputStream;
27 import java.io.OutputStream;
28 import java.util.Vector;
29
30 /***
31 * Interface for HylaFAX clients.
32 *
33 * @author Steven Jardine <steve@mjnservices.com>
34 */
35 public interface Client extends ClientProtocol, TransferEventSource,
36 ConnectionEventSource {
37
38 /***
39 * Create a new job in the server
40 *
41 * @return a new Job instance on the server
42 * @exception ServerResponseException
43 * @exception IOException
44 * an IO error occurred while communicating with the server
45 */
46 public Job createJob() throws ServerResponseException, IOException;
47
48 /***
49 * Delete the given done or suspended job @
50 *
51 * param job the (done or suspended) job to delete
52 *
53 * @exception ServerResponseException
54 * @exception IOException
55 * an IO error occurred while communicating with the server
56 */
57 public void delete(Job job) throws ServerResponseException, IOException;
58
59 /***
60 * GET the named file, FTP style.
61 *
62 * @param path
63 * the name of the file to GET. This can be a full or partial
64 * path.
65 * @param out
66 * the OutputStream to write the file data to
67 * @exception IOException
68 * an IO error occurred
69 * @exception ServerResponseException
70 * the server reported an error
71 * @exception FileNotFoundException
72 * the given path does not exist
73 */
74 public void get(String path, OutputStream out) throws IOException,
75 FileNotFoundException, ServerResponseException;
76
77 /***
78 * get a Job instance for the given job id
79 *
80 * @param id
81 * the id of the job to get
82 * @exception ServerResponseException
83 * @exception IOException
84 * an IO error occurred while communicating with the server
85 */
86 public Job getJob(long id) throws ServerResponseException, IOException;
87
88 /***
89 * get a long-style listing of files in the current directory. NOTE: this
90 * calls the list() method internally with the "." path.
91 *
92 * @exception IOException
93 * an IO error occurred
94 * @exception FileNotFoundException
95 * the "." path doesn't exist
96 * @exception ServerResponseException
97 * the server reported an error
98 * @return a Vector of Strings containing the list information
99 */
100 public Vector getList() throws IOException, FileNotFoundException,
101 ServerResponseException;
102
103 /***
104 * get a long-style listing of files in the given directory. NOTE: this
105 * calls the list() method internally.
106 *
107 * @param path
108 * the path that we're interested in finding the contents of
109 * @exception IOException
110 * an IO error occurred
111 * @exception FileNotFoundException
112 * the given path doesn't exist
113 * @exception ServerResponseException
114 * the server reported an error
115 * @return a Vector of Strings containing the list information
116 */
117 public Vector getList(String path) throws IOException,
118 FileNotFoundException, ServerResponseException;
119
120 /***
121 * get name list of files in the current directory. Similar to getList() but
122 * returns filenames only where getList() returns other, system dependant
123 * information.
124 *
125 * @exception IOException
126 * an IO error occurred
127 * @exception ServerResponseException
128 * the server reported an error
129 * @exception FileNotFoundException
130 * the requested path does not exist
131 * @return Vector of Strings containing filenames
132 */
133 public Vector getNameList() throws IOException, ServerResponseException,
134 FileNotFoundException;
135
136 /***
137 * get name list of files in the given directory. Similar to getList() but
138 * returns filenames only where getList() returns other, system dependant
139 * information.
140 *
141 * @param path
142 * the path of the directory that we want the name list of
143 * @exception IOException
144 * an IO error occurred
145 * @exception ServerResponseException
146 * the server reported an error
147 * @exception FileNotFoundException
148 * the requested path does not exist
149 * @return Vector of Strings containing filenames
150 */
151 public Vector getNameList(String path) throws IOException,
152 ServerResponseException, FileNotFoundException;
153
154 /***
155 * check whether passive transfers have been enabled
156 *
157 * @return true if passive transfers are enabled, false otherwise
158 */
159 public boolean getPassive();
160
161 /***
162 * interrupt the given job
163 *
164 * @param job
165 * the job to interrupt
166 * @exception ServerResponseException
167 * @exception IOException
168 * an IO error occurred while communicating with the server
169 */
170 public void interrupt(Job job) throws ServerResponseException, IOException;
171
172 /***
173 * kill the given job
174 *
175 * @param job
176 * the job to kill
177 * @exception ServerResponseException
178 * @exception IOException
179 * an IO error occurred while communicating with the server
180 */
181 public void kill(Job job) throws ServerResponseException, IOException;
182
183 /***
184 * set the transfer mode. valid mode values are MODE_* listed in the
185 * ClientProtocol class.
186 *
187 * @param mode
188 * the new mode setting
189 * @exception IOException
190 * an io error occurred talking to the server
191 * @exception ServerResponseException
192 * the server replied with an error code
193 */
194 public void mode(char mode) throws IOException, ServerResponseException;
195
196 /***
197 * put a file with a unique name. NOTE: this calls stou() internally.
198 *
199 * @exception IOException
200 * a socket IO error occurred
201 * @exception ServerResponseException
202 * the server responded with an error code
203 * @return the name of the file created
204 */
205 public String put(InputStream in) throws IOException,
206 ServerResponseException;
207
208 /***
209 * store a file. NOTE: this calls stor() internally.
210 *
211 * @param pathname
212 * name of file to store on server (where to put the file on the
213 * server)
214 * @exception IOException
215 * a socket IO error occurred
216 * @exception ServerResponseException
217 * the server responded with an error
218 */
219 public void put(InputStream in, String pathname) throws IOException,
220 ServerResponseException;
221
222 /***
223 * put a temp file, the data is stored in a uniquely named file on the
224 * server. The remote temp file is deleted when the connection is closed.
225 * NOTE: this calls stot() internally.
226 *
227 * @exception IOException
228 * io error occurred talking to the server
229 * @exception ServerResponseException
230 * server replied with error code
231 * @return the filename of the temp file
232 */
233 public String putTemporary(InputStream data) throws IOException,
234 ServerResponseException;
235
236 /***
237 * enable or disable passive transfers
238 *
239 * @param passive
240 * indicates whether passive transfers should be used
241 */
242 public void setPassive(boolean passive);
243
244 /***
245 * submit the given job to the scheduler
246 *
247 * @param job
248 * the Job to submit
249 * @exception ServerResponseException
250 * @exception IOException
251 * an IO error occurred while communicating with the server
252 */
253 public void submit(Job job) throws ServerResponseException, IOException;
254
255 /***
256 * suspend the given job from the scheduler
257 *
258 * @param job
259 * the Job to suspend
260 * @exception ServerResponseException
261 * @exception IOException
262 * an IO error occurred while communicating with the server
263 */
264 public void suspend(Job job) throws ServerResponseException, IOException;
265
266 /***
267 * Specify the type of file being sent.
268 *
269 * @param type
270 * the type of file being sent.
271 * @throws ServerResponseException
272 * @throws IOException
273 */
274 public void type(char type) throws ServerResponseException, IOException;
275
276 /***
277 * wait for the given job to complete
278 *
279 * @param job
280 * the job to wait for
281 * @exception ServerResponseException
282 * @exception IOException
283 * an IO error occurred while communicating with the server
284 */
285 public void wait(Job job) throws ServerResponseException, IOException;
286
287 }