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    import net.dpml.library.info.Scope;
024    import net.dpml.library.info.ResourceDirective.Classifier;
025    
026    import net.dpml.transit.Artifact;
027    
028    import net.dpml.lang.Category;
029    import net.dpml.lang.Version;
030    
031    import net.dpml.util.Resolver;
032    
033    /**
034     * The Resource interface describes infomation about a published resource.
035     *
036     * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
037     * @version 1.2.0
038     */
039    public interface Resource extends Dictionary, Resolver
040    {
041       /**
042        * System property name used to declare the decimal versioning enabled flag.
043        */
044        public static final String DECIMAL_VERSIONING_KEY = "project.decimal.versioning.enabled";
045    
046       /**
047        * Return the singleton library.
048        * @return the library
049        */
050        Library getLibrary();
051    
052       /**
053        * Return the name of the resource.
054        * @return the resource name
055        */
056        String getName();
057        
058       /**
059        * Return the resource version.
060        * @return the version
061        */
062        String getVersion();
063        
064       /**
065        * Return the statutory resource version.
066        * @return the version
067        */
068        String getStatutoryVersion();
069        
070       /**
071        * Return the decimal version.
072        * @return the version
073        */
074        Version getDecimalVersion();
075        
076       /**
077        * Return the fully qualified path to the resource.
078        * @return the path
079        */
080        String getResourcePath();
081    
082       /**
083        * Return the basedir for this resource.
084        * @return the base directory (possibly null)
085        */
086        File getBaseDir();
087    
088       /**
089        * Return the info block.
090        * @return the info block
091        */
092        Info getInfo();
093        
094       /**
095        * Return the resource classifier.
096        * @return the classifier (LOCAL, EXTERNAL or ANONYMOUS)
097        */
098        Classifier getClassifier();
099        
100       /**
101        * Return the expanded array of types associated with the resource.
102        * The returned array is a function of the types declared by a resource
103        * expanded relative to any types implied by processor dependencies.
104        * @return the type array
105        */
106        Type[] getTypes();
107        
108       /**
109        * Test if this resource is associated with a type of the supplied name.
110        * @param type the type id
111        * @return TRUE if this resource produces an artifact of the supplied type
112        */
113        boolean isa( String type );
114        
115       /**
116        * Return a resource type relative to a supplied type id.
117        * @param id the type name to retrieve
118        * @return the type instance
119        */
120        Type getType( String id );
121        
122       /**
123        * Construct an artifact for the supplied type.
124        * @param type the resource type id
125        * @return the artifact
126        */
127        Artifact getArtifact( String type );
128        
129       /**
130        * Construct an unversion link artifact for the supplied type.
131        * @param type the resource type id
132        * @return the link artifact
133        */
134        Artifact getLinkArtifact( String type );
135        
136       /**
137        * Return the enclosing parent module.
138        * @return the enclosing module of null if this a top-level module.
139        */
140        Module getParent();
141        
142       /**
143        * Return an array of resource that are providers to this resource.
144        * @param scope the operational scope
145        * @param expand if true include transitive dependencies
146        * @param sort if true the array will sorted relative to dependencies
147        * @return the resource providers
148        */
149        Resource[] getProviders( Scope scope, boolean expand, boolean sort );
150        
151       /**
152        * Return an array of resource that are providers to this resource. If
153        * the supplied scope is BUILD the returned resource array is equivalent
154        * <src>getProviders( Scope.BUILD, .. )</src>.  If the scope is RUNTIME
155        * the returned resource array includes BUILD and RUNTIME resources. If 
156        * the scope is TEST the returned array includes BUILD, RUNTIME and TEST
157        * resources.
158        * @param scope the scope of aggregation to be applied to the selection
159        * @param expand if TRUE include transitive dependencies
160        * @param sort if true the array will sorted relative to dependencies
161        * @return the resource providers
162        */
163        Resource[] getAggregatedProviders( Scope scope, boolean expand, boolean sort );
164        
165       /**
166        * Return a sorted and filtered array of providers. Resources not declaring
167        * the "jar" type as a produced type are excluded from selection.  The 
168        * resource array will include transitive dependencies.  The method is 
169        * suitable for the construction of build and test phase classloaders.
170        *
171        * @param scope the aggregation scope
172        * @return the scoped resource chain
173        */
174        Resource[] getClasspathProviders( Scope scope );
175    
176       /**
177        * Return an array of runtime providers filtered relative to a supplied
178        * classloading category.  Resources not declaring the "jar" type as a 
179        * produced type are excluded from selection.  The resource array returned 
180        * from this operation is a sorted transitive sequence excluding all 
181        * resource references by any category higher than the supplied category.
182        * This method is typically used to construct information suitable for 
183        * the gerneration of plugin metadata.
184        *
185        * @param category the classloader category
186        * @return the category scoped resource chain
187        */
188        Resource[] getClasspathProviders( Category category );
189    
190       /**
191        * Return an array of resources that are consumers of this resource.
192        * @param expand if true the returned array includes consumers associated
193        *   through transitive dependency relationships, otherwise the array is 
194        *   limited to direct consumers
195        * @param sort if true the array is sorted relative to depenency relationships
196        * @return the array of consumer projects
197        */
198        Resource[] getConsumers( boolean expand, boolean sort );
199        
200       /**
201        * Return an array of filters associated with the resource.
202        * @return the array of filters
203        */
204        Filter[] getFilters();
205        
206       /**
207        * Return a filename using the layout strategy employed by the cache.
208        * @param id the artifact type
209        * @return the filename
210        */
211        String getLayoutPath( String id );
212    
213       /**
214        * Return the array of production data.
215        * @return the associated production data
216        */
217        Data[] getData();
218    }