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 java.io.File;
022
023 /**
024 * The Library interface is the application root for module management.
025 *
026 * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
027 * @version 1.1.2
028 */
029 public interface Library
030 {
031 /**
032 * Index filename.
033 */
034 public static final String INDEX_FILENAME = "index.xml";
035
036 /**
037 * Utility operation to sort a collection of resources.
038 * @param resources the resources to sort
039 * @return the sorted resource array
040 */
041 Resource[] sort( Resource[] resources );
042
043 /**
044 * Return a array of the top-level modules within the library.
045 * @return the module array
046 */
047 Module[] getModules();
048
049 /**
050 * Return a array of all modules in the library.
051 * @return module array
052 */
053 Module[] getAllModules();
054
055 /**
056 * Return a named module.
057 * @param ref the fully qualified module name
058 * @return the module
059 * @exception ModuleNotFoundException if the module cannot be found
060 */
061 Module getModule( String ref ) throws ModuleNotFoundException;
062
063 /**
064 * Recursively lookup a resource using a fully qualified reference.
065 * @param ref the fully qualified resource name
066 * @return the resource instance
067 * @exception ResourceNotFoundException if the resource cannot be found
068 */
069 Resource getResource( String ref ) throws ResourceNotFoundException;
070
071 /**
072 * <p>Select a set of resource matching a supplied a resource selection
073 * constraint. The constraint may contain the wildcards '**' and '*'.
074 * @param criteria the selection criteria
075 * @param sort if true the returned array will be sorted relative to dependencies
076 * otherwise the array will be sorted alphanumerically with respect to the resource
077 * path
078 * @return an array of resources matching the selction criteria
079 */
080 Resource[] select( String criteria, boolean sort );
081
082 /**
083 * <p>Select a set of resource matching a supplied a resource selection
084 * constraint. The constraint may contain the wildcards '**' and '*'.
085 * @param local if true limit the selection to local projects
086 * @param criteria the selection criteria
087 * @param sort if true the returned array will be sorted relative to dependencies
088 * otherwise the array will be sorted alphanumerically with respect to the resource
089 * path
090 * @return an array of resources matching the selction criteria
091 */
092 Resource[] select( String criteria, boolean local, boolean sort );
093
094 /**
095 * Select all local projects with a basedir equal to or depper than the supplied
096 * directory.
097 * @param base the reference basedir
098 * @return an array of projects within or lower than the supplied basedir
099 */
100 Resource[] select( File base );
101
102 /**
103 * Select all local projects relative to the supplied basedir.
104 * @param base the reference basedir
105 * @param self if true and the basedir resolves to a project then include the project
106 * otherwise the project will be expluded from selection
107 * @return an array of projects relative to the basedir
108 */
109 Resource[] select( File base, boolean self );
110
111 /**
112 * Locate a resource relative to a base directory.
113 * @param base the base directory
114 * @return a resource with a matching basedir
115 * @exception ResourceNotFoundException if resource match relative to the supplied base
116 */
117 Resource locate( File base ) throws ResourceNotFoundException;
118
119 }