001    /*
002     * Copyright 2005 Stephen J. McConnell
003     *
004     * Licensed  under the  Apache License,  Version 2.0  (the "License");
005     * you may not use  this file  except in  compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     *   http://www.apache.org/licenses/LICENSE-2.0
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed  under the  License is distributed on an "AS IS" BASIS,
012     * WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
013     * implied.
014     *
015     * See the License for the specific language governing permissions and
016     * limitations under the License.
017     */
018    
019    package net.dpml.library;
020    
021    import net.dpml.library.info.ModuleDirective;
022    
023    /**
024     * The Modele interface defines a node within a module hierachy.
025     *
026     * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
027     * @version 1.1.2
028     */
029    public interface Module extends Resource
030    {
031       /**
032        * Return an array of immediate resources contained within the
033        * module.
034        * @return the resource array
035        */
036        Resource[] getResources();
037        
038       /**
039        * Return a resource using a supplied name.
040        * @param ref a path relative to the module
041        * @return the resource array
042        * @exception ResourceNotFoundException if the ref value is not recognized
043        */
044        Resource getResource( String ref ) throws ResourceNotFoundException;
045        
046       /**
047        * Return the array of modules that are direct children of this module.
048        * @return the child modules
049        */
050        Module[] getModules();
051        
052       /**
053        * Return the array of modules that are descendants of this module.
054        * @return the descendants module array
055        */
056        Module[] getAllModules();
057        
058       /**
059        * Return a module using a supplied reference.
060        * @param ref a path relative to the module
061        * @return the module array
062        * @exception ModuleNotFoundException if the ref value is not recognized
063        */
064        Module getModule( String ref ) throws ModuleNotFoundException;
065        
066       /**
067        * <p>Select a set of resource matching a supplied a resource selection 
068        * constraint.  The constraint may contain the wildcards '**' and '*'.
069        * @param local if true limit the selection to local projects
070        * @param criteria the selection criteria
071        * @param sort if true the returned array will be sorted relative to dependencies
072        *   otherwise the array will be sorted alphanumerically with respect to the resource
073        *   path
074        * @return an array of resources matching the selction criteria
075        */
076        Resource[] select( String criteria, boolean local, boolean sort );
077    
078       /**
079        * Return a directive suitable for publication as an external description.
080        * @return the module directive
081        */
082        ModuleDirective export();
083    
084    }