KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > modules > ruby > api > project > rake > RakeArtifact


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.modules.ruby.api.project.rake;
21
22 import java.io.File JavaDoc;
23 import java.net.MalformedURLException JavaDoc;
24 import java.net.URI JavaDoc;
25 import java.net.URL JavaDoc;
26 import java.util.ArrayList JavaDoc;
27 import java.util.Collections JavaDoc;
28 import java.util.HashSet JavaDoc;
29 import java.util.List JavaDoc;
30 import java.util.Properties JavaDoc;
31 import java.util.Set JavaDoc;
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 SimpleRakeArtifact?)
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.modules.ruby.spi.project.support.rake.SimpleRakeArtifact
49  * @author Jesse Glick
50  */

51 public abstract class RakeArtifact {
52
53     private final Properties JavaDoc PROPS = new Properties JavaDoc();
54     
55     /**
56      * Empty constructor for use from subclasses.
57      */

58     protected RakeArtifact() {}
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc
109     public URI JavaDoc getArtifactLocation() {
110         return getArtifactLocations()[0];
111     }
112
113     private static final Set JavaDoc<String JavaDoc> warnedClasses = Collections.synchronizedSet(new HashSet JavaDoc<String JavaDoc>());
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 JavaDoc[] getArtifactLocations() {
125         String JavaDoc 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 JavaDoc[]{getArtifactLocation()};
130     }
131
132     /**
133      * Returns identifier of the RakeArtifact 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 JavaDoc 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 JavaDoc
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 JavaDoc artifactLocation) {
159         assert !artifactLocation.isAbsolute() ||
160             (!artifactLocation.isOpaque() && "file".equals(artifactLocation.getScheme())) // NOI18N
161
: artifactLocation;
162         URL JavaDoc artifact;
163         try {
164             // XXX this should probably use something in PropertyUtils?
165
artifact = getScriptLocation().toURI().resolve(artifactLocation).normalize().toURL();
166         } catch (MalformedURLException JavaDoc 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         URI JavaDoc artifactLocations[] = getArtifactLocations();
191         List JavaDoc<FileObject> l = new ArrayList JavaDoc<FileObject>();
192         for (int i=0; i<artifactLocations.length; i++) {
193             FileObject fo = getArtifactFile(artifactLocations[i]);
194             if (fo != null) {
195                 l.add(fo);
196             }
197         }
198         return l.toArray(new FileObject[l.size()]);
199     }
200     
201     /**
202      * Convenience method to find the actual script file, if it currently exists.
203      * Uses {@link #getScriptLocation}.
204      * The script must exist on disk (Ant cannot run scripts from NetBeans
205      * filesystems unless they are represented on disk).
206      * @return the Ant build script file, or null if it could not be found
207      */

208     public final FileObject getScriptFile() {
209         FileObject fo = FileUtil.toFileObject(getScriptLocation());
210         assert fo == null || FileUtil.toFile(fo) != null : fo;
211         return fo;
212     }
213     
214     /**
215      * Find the project associated with this script, if any.
216      * The default implementation uses {@link #getScriptLocation} and {@link FileOwnerQuery},
217      * but subclasses may override that to return something else.
218      * @return the associated project, or null if there is none or it could not be located
219      */

220     public Project getProject() {
221         return FileOwnerQuery.getOwner(getScriptLocation().toURI());
222     }
223
224     /**
225      * Optional properties which are used for Ant target execution. Only
226      * properties necessary for customization of Ant target execution should
227      * be used. These properties are stored in project.xml of project using
228      * this artifact so care should be taken in defining what properties
229      * are used, e.g. never use absolute path like values
230      * @since 1.5
231      */

232     public Properties JavaDoc getProperties() {
233         return PROPS;
234     }
235     
236 }
237
Popular Tags