AntArtifact


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  
20  package org.netbeans.api.project.ant;
21  
22  import java.io.File  ;
23  import java.net.MalformedURLException  ;
24  import java.net.URI  ;
25  import java.net.URL  ;
26  import java.util.ArrayList  ;
27  import java.util.Collections  ;
28  import java.util.HashSet  ;
29  import java.util.List  ;
30  import java.util.Properties  ;
31  import java.util.Set  ;
32  import org.netbeans.api.project.FileOwnerQuery;
33  import org.netbeans.api.project.Project;
34  import org.openide.ErrorManager;
35  import org.openide.filesystems.FileObject;
36  import org.openide.filesystems.FileUtil;
37  import org.openide.filesystems.URLMapper;
38  
39  // XXX may also need displayName field (any default? or only in SimpleAntArtifact?)
40  
41  /**
42   * Represents one artifact of an Ant build.
43   * For example, if a build script is known to generate a JAR of a certain name
44   * as a result of running a certain target, this object will name that JAR
45   * and point to the script and target responsible for creating it. You can use
46   * this information to add an <samp>&lt;ant&gt;</samp> task to another project
47   * which will generate that JAR as a dependency before using it.
48   * @see org.netbeans.spi.project.support.ant.SimpleAntArtifact
49   * @author Jesse Glick
50   */
51  public abstract class AntArtifact {
52  
53      private final Properties   PROPS = new Properties  ();
54      
55      /**
56       * Empty constructor for use from subclasses.
57       */
58      protected AntArtifact() {}
59      
60      /**
61       * Get the type of the build artifact.
62       * This can refer to both the physical content type or format;
63       * and to the intended category of usage.
64       * Typically a given client (e.g. superproject) will be interested
65       * in only a certain artifact type for a certain purpose, e.g.
66       * inclusion in a Java classpath.
67       * <p>
68       * Particular type identifiers should be agreed upon between
69       * providers and clients.
70       * For example, <a HREF="@JAVA/PROJECT@/org/netbeans/api/java/project/JavaProjectConstants.html#ARTIFACT_TYPE_JAR"><code>JavaProjectConstants.ARTIFACT_TYPE_JAR</code></a>
71       * is defined for JAR outputs.
72       * Others may be defined as needed; for example, tag library JARs,
73       * WARs, EJB JARs, deployment descriptor fragments, etc.
74       * XXX format - NMTOKEN maybe
75       * @return the type (format or usage) of the build artifact
76       */
77      public abstract String   getType();
78      
79      /**
80       * Get a location for the Ant script that is able to produce this artifact.
81       * The name <samp>build.xml</samp> is conventional.
82       * @return the location of an Ant project file (might not currently exist)
83       */
84      public abstract File   getScriptLocation();
85      
86      /**
87       * Get the name of the Ant target that is able to produce this artifact.
88       * E.g. <samp>jar</samp> would be conventional for JAR artifacts.
89       * @return an Ant target name
90       */
91      public abstract String   getTargetName();
92      
93      /**
94       * Get the name of an Ant target that will delete this artifact.
95       * Typically this should be <samp>clean</samp>.
96       * The target may delete other build products as well.
97       * @return an Ant target name
98       */
99      public abstract String   getCleanTargetName();
100     
101     /**
102      * Get the location of the build artifact relative to the Ant script.
103      * See {@link #getArtifactLocations}.
104      * @return a URI to the build artifact, resolved relative to {@link #getScriptLocation};
105      *         may be either relative, or an absolute <code>file</code>-protocol URI
106      * @deprecated use {@link #getArtifactLocations} instead
107      */
108     @Deprecated  
109     public URI   getArtifactLocation() {
110         return getArtifactLocations()[0];
111     }
112 
113     private static final Set  <String  > warnedClasses = Collections.synchronizedSet(new HashSet  <String  >());
114     /**
115      * Get the locations of the build artifacts relative to the Ant script.
116      * For example, <samp>dist/mylib.jar</samp>. The method is not defined 
117      * as abstract only for backward compatibility reasons. <strong>It must be
118      * overridden.</strong> The order is important and should stay the same
119      * unless the artifact was changed.
120      * @return an array of URIs to the build artifacts, resolved relative to {@link #getScriptLocation};
121      *         may be either relative, or an absolute <code>file</code>-protocol URI
122      * @since 1.5
123      */
124     public URI  [] getArtifactLocations() {
125         String   name = getClass().getName();
126         if (warnedClasses.add(name)) {
127             ErrorManager.getDefault().log(ErrorManager.WARNING, "Warning: " + name + ".getArtifactLocations() must be overridden");
128         }
129         return new URI  []{getArtifactLocation()};
130     }
131 
132     /**
133      * Returns identifier of the AntArtifact which must be <strong>unique within
134      * one project</strong>. By default it is target name which produces the
135      * artifact, but if your target produces more that one artifact then
136      * you must override this method and uniquely identify each artifact.
137      */
138     public String   getID() {
139         return getTargetName();
140     }
141 
142     /**
143      * Convenience method to find the actual artifact, if it currently exists.
144      * See {@link #getArtifactFiles}.
145      * @return the artifact file on disk, or null if it could not be found
146      * @deprecated use {@link #getArtifactFiles} instead
147      */
148     @Deprecated  
149     public final FileObject getArtifactFile() {
150         FileObject fos[] = getArtifactFiles();
151         if (fos.length > 0) {
152             return fos[0];
153         } else {
154             return null;
155         }
156     }
157     
158     private FileObject getArtifactFile(URI   artifactLocation) {
159         assert !artifactLocation.isAbsolute() ||
160             (!artifactLocation.isOpaque() && "file".equals(artifactLocation.getScheme())) // NOI18N
161             : artifactLocation;
162         URL   artifact;
163         try {
164             // XXX this should probably use something in PropertyUtils?
165             artifact = getScriptLocation().toURI().resolve(artifactLocation).normalize().toURL();
166         } catch (MalformedURLException   e) {
167             ErrorManager.getDefault().notify(ErrorManager.INFORMATIONAL, e);
168             return null;
169         }
170         FileObject fo = URLMapper.findFileObject(artifact);
171         if (fo != null) {
172             assert FileUtil.toFile(fo) != null : fo;
173             return fo;
174         } else {
175             return null;
176         }
177     }
178     
179     /**
180      * Convenience method to find the actual artifacts, if they currently exist.
181      * Uses {@link #getScriptFile} or {@link #getScriptLocation} and resolves {@link #getArtifactLocations} from it.
182      * Note that a project which has been cleaned more recently than it has been built
183      * will generally not have the build artifacts on disk and so this call may easily
184      * return empty array. If you do not rely on the actual presence of the file but just need to
185      * refer to it abstractly, use {@link #getArtifactLocations} instead.
186      * @return the artifact files which exist on disk, or empty array if none could be found
187      * @since 1.5
188      */
189     public final FileObject[] getArtifactFiles() {
190         List  <FileObject> l = new ArrayList  <FileObject>();
191         for (URI   artifactLocation : getArtifactLocations()) {
192             FileObject fo = getArtifactFile(artifactLocation);
193             if (fo != null) {
194                 l.add(fo);
195             }
196         }
197         return l.toArray(new FileObject[l.size()]);
198     }
199     
200     /**
201      * Convenience method to find the actual script file, if it currently exists.
202      * Uses {@link #getScriptLocation}.
203      * The script must exist on disk (Ant cannot run scripts from NetBeans
204      * filesystems unless they are represented on disk).
205      * @return the Ant build script file, or null if it could not be found
206      */
207     public final FileObject getScriptFile() {
208         FileObject fo = FileUtil.toFileObject(getScriptLocation());
209         assert fo == null || FileUtil.toFile(fo) != null : fo;
210         return fo;
211     }
212     
213     /**
214      * Find the project associated with this script, if any.
215      * The default implementation uses {@link #getScriptLocation} and {@link FileOwnerQuery},
216      * but subclasses may override that to return something else.
217      * @return the associated project, or null if there is none or it could not be located
218      */
219     public Project getProject() {
220         return FileOwnerQuery.getOwner(getScriptLocation().toURI());
221     }
222 
223     /**
224      * Optional properties which are used for Ant target execution. Only
225      * properties necessary for customization of Ant target execution should
226      * be used. These properties are stored in project.xml of project using 
227      * this artifact so care should be taken in defining what properties
228      * are used, e.g. never use absolute path like values
229      * @since 1.5
230      */
231     public Properties   getProperties() {
232         return PROPS;
233     }
234     
235 }
236
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags