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.tools;
020    
021    import java.io.File;
022    
023    import net.dpml.library.Library;
024    import net.dpml.library.Resource;
025    import net.dpml.library.info.Scope;
026    
027    import org.apache.tools.ant.Project;
028    import org.apache.tools.ant.types.Path;
029    
030    /**
031     * Project context.
032     *
033     * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
034     * @version 1.1.3
035     */
036    public interface Context
037    {
038       /**
039        * Return the associated project.
040        * @return the ant project
041        */
042        Project getProject();
043        
044       /**
045        * Return the value of a property.
046        * @param key the property key
047        * @return the property value or null if undefined
048        */
049        String getProperty( String key );
050        
051       /**
052        * Return the value of a property. If the project contains a declaration 
053        * for the property then that value will be returned, otherwise the property
054        * will be resolved relative to the current resource.
055        *
056        * @param key the property key
057        * @param value the default value
058        * @return the property value or null if undefined
059        */
060        String getProperty( String key, String value );
061        
062       /**
063        *Initialize the context.
064        */
065        void init();
066        
067       /**
068        * Return an Ant path suitable for compile or runtime usage. If the supplied scope is 
069        * less than Scope.RUNTIME a runtime path is returned otherwise the test path is 
070        * returned.
071        *
072        * @param scope the build scope
073        * @return the path object
074        */
075        Path getPath( Scope scope );
076        
077       /**
078        * Return the active resource.
079        * @return the resource definition
080        */
081        Resource getResource();
082        
083       /**
084        * Return the resource library.
085        * @return the library
086        */
087        Library getLibrary();
088        
089       /**
090        * Return the project source directory.
091        * @return the directory
092        */
093        File getSrcDirectory();
094        
095       /**
096        * Return the project source main directory.
097        * @return the directory
098        */
099        File getSrcMainDirectory();
100        
101       /**
102        * Return the project source test directory.
103        * @return the directory
104        */
105        File getSrcTestDirectory();
106        
107       /**
108        * Return the project source docs directory.
109        * @return the directory
110        */
111        File getSrcDocsDirectory();
112        
113       /**
114        * Return the project etc directory.
115        * @return the directory
116        */
117        File getEtcDirectory();
118    
119       /**
120        * Return the project etc/main directory.
121        * @return the directory
122        */
123        File getEtcMainDirectory();
124    
125       /**
126        * Return the project etc/test directory.
127        * @return the directory
128        */
129        File getEtcTestDirectory();
130    
131       /**
132        * Return the project etc/data directory.
133        * @return the directory
134        */
135        File getEtcDataDirectory();
136    
137       /**
138        * Return the project target directory.
139        * @return the directory
140        */
141        File getTargetDirectory();
142        
143       /**
144        * Return a directory within the target directory.
145        * @param path the path
146        * @return the directory
147        */
148        File getTargetDirectory( String path );
149        
150       /**
151        * Return the project target temp directory.
152        * @return the directory
153        */
154        File getTargetTempDirectory();
155        
156       /**
157        * Return the project target build directory.
158        * @return the directory
159        */
160        File getTargetBuildDirectory();
161        
162       /**
163        * Return the project target build main directory.
164        * @return the directory
165        */
166        File getTargetBuildMainDirectory();
167        
168       /**
169        * Return the project target build test directory.
170        * @return the directory
171        */
172        File getTargetBuildTestDirectory();
173        
174       /**
175        * Return the project target build docs directory.
176        * @return the directory
177        */
178        File getTargetBuildDocsDirectory();
179        
180       /**
181        * Return the project target root classes directory.
182        * @return the directory
183        */
184        File getTargetClassesDirectory();
185        
186       /**
187        * Return the project target main classes directory.
188        * @return the directory
189        */
190        File getTargetClassesMainDirectory();
191        
192       /**
193        * Return the project target test classes directory.
194        * @return the directory
195        */
196        File getTargetClassesTestDirectory();
197        
198       /**
199        * Return the project target reports directory.
200        * @return the directory
201        */
202        File getTargetReportsDirectory();
203        
204       /**
205        * Return the project target test reports directory.
206        * @return the directory
207        */
208        File getTargetReportsTestDirectory();
209        
210       /**
211        * Return the project target main reports directory.
212        * @return the directory
213        */
214        File getTargetReportsMainDirectory();
215        
216       /**
217        * Return the project target javadoc reports directory.
218        * @return the directory
219        */
220        File getTargetReportsJavadocDirectory();
221        
222       /**
223        * Return the project target reports docs directory.
224        * @return the directory
225        */
226        File getTargetDocsDirectory();
227        
228       /**
229        * Return the project target test directory.
230        * @return the directory
231        */
232        File getTargetTestDirectory();
233        
234       /**
235        * Return the project target deliverables directory.
236        * @return the directory
237        */
238        File getTargetDeliverablesDirectory();
239        
240       /**
241        * Return the project target deliverables directory.
242        * @param type the deliverable type
243        * @return the directory
244        */
245        File getTargetDeliverable( String type );
246        
247       /**
248        * Create a file relative to the resource basedir.
249        * @param path the relative path
250        * @return the directory
251        */
252        File createFile( String path );
253        
254       /**
255        * Return a filename using the layout strategy employed by the cache.
256        * @param id the artifact type
257        * @return the filename
258        */
259        String getLayoutFilename( String id );
260       
261       /**
262        * Return the directory path representing the module structure and type
263        * using the layout strategy employed by the cache.
264        * @param id the artifact type
265        * @return the path from the root of the cache to the directory containing the artifact
266        */
267        String getLayoutBase( String id );
268        
269       /**
270        * Return the full path to an artifact using the layout employed by the cache.
271        * @param id the artifact type
272        * @return the full path including base path and filename
273        */
274        String getLayoutPath( String id );
275        
276       /**
277        * Utility operation to construct a new classpath path instance.
278        * @param scope the build scope
279        * @return the path
280        */
281        Path createPath( Scope scope );
282        
283       /**
284        * Utility operation to construct a new path using a supplied array of resources.
285        * @param resources the resource to use in path construction
286        * @return the path
287        */
288        Path createPath( Resource[] resources );
289        
290       /**
291        * Utility operation to construct a new path using a supplied array of resources.
292        * @param resources the resources to use in path construction
293        * @param resolve if true force local caching of the artifact 
294        * @param filter if true restrict path entries to resources that produce jars
295        * @return the path
296        */
297        Path createPath( Resource[] resources, boolean resolve, boolean filter );
298    }
299