TraversableSource


1   /* 
2    * Copyright 2002-2004 The Apache Software Foundation
3    * Licensed  under the  Apache License,  Version 2.0  (the "License");
4    * you may not use  this file  except in  compliance with the License.
5    * You may obtain a copy of the License at 
6    * 
7    *   http://www.apache.org/licenses/LICENSE-2.0
8    * 
9    * Unless required by applicable law or agreed to in writing, software
10   * distributed  under the  License is distributed on an "AS IS" BASIS,
11   * WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
12   * implied.
13   * 
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.excalibur.source;
18  
19  
20  import java.util.Collection  ;
21  
22  /**
23   * A traversable source is a source that can have children and
24   * a parent, like a file system.
25   *
26   * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
27   * @version CVS $Revision: 1.5 $ $Date: 2004/02/28 11:47:26 $
28   */
29  public interface TraversableSource extends Source {
30  
31      /**
32       * Is this source a collection, i.e. it possibly has children ?
33       * For a filesystem-based implementation, this would typically mean that
34       * this source represents a directory and not a file.
35       * 
36       * @return true if the source exists and is traversable.
37       */
38      boolean isCollection();
39      
40      /**
41       * Get the children of this source if this source is traversable.
42       * <p>
43       * <em>Note:</em> only those sources actually fetched from the
44       * collection need to be released using the {@link SourceResolver}.
45       * 
46       * @see #isCollection()
47       * @return a collection of {@link Source}s (actually most probably <code>TraversableSource</code>s).
48       * @throws SourceException this source is not traversable, or if some problem occurs.
49       */
50      Collection   getChildren() throws SourceException;
51      
52      /**
53       * Get a child of this source, given its name. Note that the returned source
54       * may not actually physically exist, and that this must be checked using
55       * {@link Source#exists()}.
56       * 
57       * @param name the child name.
58       * @return the child source.
59       * @throws SourceException if this source is not traversable or if some other
60       *         error occurs.
61       */
62      Source getChild(String   name) throws SourceException;
63      
64      /**
65       * Return the name of this source relative to its parent.
66       *
67       * @return the name
68       */
69      String   getName();
70      
71      /**
72       * Get the parent of this source as a {@link Source} object.
73       * 
74       * @return the parent source, or <code>null</code> if this source has no parent.
75       * @throws SourceException if some problem occurs.
76       */
77      Source getParent() throws SourceException;
78  }
79
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags