001: /*
002: * Copyright (c) 2007, intarsys consulting GmbH
003: *
004: * Redistribution and use in source and binary forms, with or without
005: * modification, are permitted provided that the following conditions are met:
006: *
007: * - Redistributions of source code must retain the above copyright notice,
008: * this list of conditions and the following disclaimer.
009: *
010: * - Redistributions in binary form must reproduce the above copyright notice,
011: * this list of conditions and the following disclaimer in the documentation
012: * and/or other materials provided with the distribution.
013: *
014: * - Neither the name of intarsys nor the names of its contributors may be used
015: * to endorse or promote products derived from this software without specific
016: * prior written permission.
017: *
018: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
019: * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
020: * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
021: * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
022: * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
023: * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
024: * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
025: * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
026: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
027: * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
028: * POSSIBILITY OF SUCH DAMAGE.
029: */
030: package de.intarsys.tools.locator;
031:
032: import java.io.IOException;
033: import java.io.InputStream;
034: import java.io.OutputStream;
035: import java.io.Reader;
036: import java.io.Writer;
037: import java.net.URL;
038:
039: import de.intarsys.tools.component.ISynchronizable;
040: import de.intarsys.tools.randomaccess.IRandomAccess;
041:
042: /**
043: * The locator specifies the physical location of a resource.
044: * <p>
045: */
046: public interface ILocator extends ISynchronizable {
047: /**
048: * The locator for the resource <code>name</code> within the context of
049: * this. This may for example be an {@link ILocator} to a file within a
050: * directory.
051: *
052: * @param name
053: * The name of the resource to be located.
054: *
055: * @return The {@link ILocator} for the resource with the name "name" within
056: * the context of this.
057: */
058: public ILocator getChild(String name);
059:
060: /**
061: * Answer <code>true</code> if the location designated by this is a
062: * directory. A directory location serves as a container for other
063: * resources, you can never <code>getInputStream</code> on this.
064: *
065: * @return Answer <code>true</code> if the location designated by this is
066: * a directory.
067: */
068: public boolean isDirectory();
069:
070: /**
071: * The full physical name of this.
072: *
073: * <p>
074: * This method returns a representation that is proprietary to the
075: * underlying physical representation, for example a file name, a SQL
076: * statement or so on.
077: * </p>
078: *
079: * @return The full physical name of the receiver.
080: */
081: public String getFullName();
082:
083: /**
084: * Return an {@link InputStream} on the data represented by the receiver.
085: *
086: * @return An {@link InputStream} on the data represented by the receiver.
087: *
088: * @throws IOException
089: */
090: public InputStream getInputStream() throws IOException;
091:
092: /**
093: * The local name of the receiver within its parent.
094: *
095: * @return The local name of the receiver within its parent.
096: */
097: public String getLocalName();
098:
099: /**
100: * The qualified local name of the receiver within its parent that includes
101: * the type specification for the destination if appropriate. This is for
102: * example a filename with its correct suffix. Some locator may return the
103: * same name as "getLocalName".
104: *
105: * @return The qualified local name of the receiver within its parent that
106: * includes the type specification for the destination if
107: * appropriate.
108: */
109: public String getTypedName();
110:
111: /**
112: * Return an {@link OutputStream} on the location represented by the
113: * receiver.
114: *
115: * @return An {@link OutputStream} on the location represented by the
116: * receiver.
117: *
118: * @throws IOException
119: */
120: public OutputStream getOutputStream() throws IOException;
121:
122: /**
123: * The {@link ILocator} that is one hierarchy level up or null. This may be
124: * for example the directory where the currently designated resource is
125: * found.
126: *
127: * @return The {@link ILocator}that is one hierarchy level up or null.
128: */
129: public ILocator getParent();
130:
131: /**
132: * The {@link IRandomAccess} for this.
133: *
134: * @return The {@link IRandomAccess} for this.
135: * @throws IOException
136: */
137: public IRandomAccess getRandomAccess() throws IOException;
138:
139: /**
140: * A {@link Reader} on the data represented by the receiver.
141: *
142: * @return A {@link Reader} on the data represented by the receiver.
143: *
144: * @throws IOException
145: */
146: public Reader getReader() throws IOException;
147:
148: /**
149: * A {@link Reader} on the data represented by the receiver for the given
150: * encoding.
151: *
152: * @param encoding
153: * The encoding.
154: *
155: * @return A {@link Reader} on the data represented by the receiver for the
156: * given encoding.
157: *
158: * @throws IOException
159: */
160: public Reader getReader(String encoding) throws IOException;
161:
162: /**
163: * The type of the resource. This may be for example a mime type or the file
164: * extension of the underlying file.
165: *
166: * @return The type of the resource
167: */
168: public String getType();
169:
170: /**
171: * A {@link Writer} on the location represented by the receiver.
172: *
173: * @return A {@link Writer} on the location represented by the receiver.
174: *
175: * @throws IOException
176: */
177: public Writer getWriter() throws IOException;
178:
179: /**
180: * A {@link Writer} on the location represented by the receiver for the
181: * given encoding.
182: *
183: * @param encoding
184: * The encoding.
185: *
186: * @return A {@link Writer} on the location represented by the receiver for
187: * the given encoding.
188: *
189: * @throws IOException
190: */
191: public Writer getWriter(String encoding) throws IOException;
192:
193: /**
194: * Answer <code>true</code> if the location designated by this exists.
195: *
196: * @return Answer <code>true</code> if the location designated by this
197: * exists.
198: */
199: public boolean exists();
200:
201: /**
202: * Return an array of {@link ILocator} that are children of the receiver
203: * that conform to <code>filter</code>. This method never returns null.
204: *
205: * @param filter
206: * The filter used to examine the child resources.
207: *
208: * @return An array of {@link ILocator} objects that conform to the filter
209: * argument.
210: *
211: * @throws IOException
212: */
213: public ILocator[] listLocators(ILocatorNameFilter filter)
214: throws IOException;
215:
216: /**
217: * The location designated by this as an {@link URL}.
218: *
219: * @return The location designated by this as an {@link URL}.
220: */
221: public URL toURL();
222:
223: /**
224: * <code>true</code> if the specified resource is read only.
225: *
226: * @return <code>true</code> if the specified resource is read only.
227: */
228: public boolean isReadOnly();
229:
230: /**
231: * Rename the complete physical name to <code>newName</code>.
232: *
233: * @param newName
234: * The new name of the {@link ILocator}. The new name is
235: * expected to contain both local and type part of the name.
236: * @throws IOException
237: */
238: public void rename(String newName) throws IOException;
239:
240: /**
241: * Delete the artifact referenced by this.
242: *
243: * @throws IOException
244: */
245: public void delete() throws IOException;
246:
247: /**
248: * Make the receiver read only. This is a one way switch only.
249: */
250: public void setReadOnly();
251: }
|