org.netbeans.modules.project.ant/1 1.12.22

org.netbeans.spi.project.support.ant
Class GeneratedFilesHelper

java.lang.Object
  extended by org.netbeans.spi.project.support.ant.GeneratedFilesHelper

public final class GeneratedFilesHelper
extends Object

Helps a project type (re-)generate, and manage the state and versioning of, build.xml and build-impl.xml.


Field Summary
static String BUILD_IMPL_XML_PATH
          Relative path from project directory to the implementation build script, build-impl.xml.
static String BUILD_XML_PATH
          Relative path from project directory to the user build script, build.xml.
static int FLAG_MISSING
          A build script is missing from disk.
static int FLAG_MODIFIED
          A build script has been modified since last generated by generateBuildScriptFromStylesheet(java.lang.String, java.net.URL).
static int FLAG_OLD_PROJECT_XML
          A build script was generated from an older version of project.xml.
static int FLAG_OLD_STYLESHEET
          A build script was generated from an older version of a stylesheet.
static int FLAG_UNKNOWN
          The build script exists, but nothing else is known about it.
 
Constructor Summary
GeneratedFilesHelper(AntProjectHelper h)
          Create a helper based on the supplied project helper handle.
GeneratedFilesHelper(FileObject d)
          Create a helper based only on a project directory.
 
Method Summary
 void generateBuildScriptFromStylesheet(String path, URL stylesheet)
          Create build.xml or nbproject/build-impl.xml from project.xml plus a supplied XSLT stylesheet.
 int getBuildScriptState(String path, URL stylesheet)
          Find what state a build script is in.
 boolean refreshBuildScript(String path, URL stylesheet, boolean checkForProjectXmlModified)
          Convenience method to refresh a build script if it can and should be.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BUILD_XML_PATH

public static final String BUILD_XML_PATH
Relative path from project directory to the user build script, build.xml.

See Also:
Constant Field Values

BUILD_IMPL_XML_PATH

public static final String BUILD_IMPL_XML_PATH
Relative path from project directory to the implementation build script, build-impl.xml.

See Also:
Constant Field Values

FLAG_MISSING

public static final int FLAG_MISSING
A build script is missing from disk. This is mutually exclusive with the other flags.

See Also:
getBuildScriptState(java.lang.String, java.net.URL), Constant Field Values

FLAG_MODIFIED

public static final int FLAG_MODIFIED
A build script has been modified since last generated by generateBuildScriptFromStylesheet(java.lang.String, java.net.URL).

Probably this means it was edited by the user.

See Also:
getBuildScriptState(java.lang.String, java.net.URL), Constant Field Values

FLAG_OLD_PROJECT_XML

public static final int FLAG_OLD_PROJECT_XML
A build script was generated from an older version of project.xml. It was last generated using a different version of project.xml, so using the current project.xml might produce a different result.

This is quite likely in the case of build.xml; in the case of build-impl.xml, it probably means that the user edited project.xml manually, since if that were modified from AntProjectHelper methods and the project were saved, the script would have been regenerated already.

See Also:
getBuildScriptState(java.lang.String, java.net.URL), Constant Field Values

FLAG_OLD_STYLESHEET

public static final int FLAG_OLD_STYLESHEET
A build script was generated from an older version of a stylesheet. It was last generated using a different (probably older) version of the XSLT stylesheet, so using the current stylesheet might produce a different result.

Probably this means the project type provider module has been upgraded since the project was last saved (in the case of build-impl.xml) or created (in the case of build.xml).

See Also:
getBuildScriptState(java.lang.String, java.net.URL), Constant Field Values

FLAG_UNKNOWN

public static final int FLAG_UNKNOWN
The build script exists, but nothing else is known about it. This flag is mutually exclusive with FLAG_MISSING but when set also sets FLAG_MODIFIED, FLAG_OLD_STYLESHEET, and FLAG_OLD_PROJECT_XML - since it is not known whether these conditions might obtain, it is safest to assume they do.

Probably this means that nbproject/genfiles.properties was deleted by the user.

See Also:
getBuildScriptState(java.lang.String, java.net.URL), Constant Field Values
Constructor Detail

GeneratedFilesHelper

public GeneratedFilesHelper(AntProjectHelper h)
Create a helper based on the supplied project helper handle.

Parameters:
h - an Ant-based project helper supplied to the project type provider

GeneratedFilesHelper

public GeneratedFilesHelper(FileObject d)
Create a helper based only on a project directory. This can be used to perform the basic refresh functionality without being the owner of the project. It is only intended for use from the offline Ant task to refresh a project, and similar special situations. For normal circumstances please use only GeneratedFilesHelper(AntProjectHelper).

Parameters:
d - the project directory
Throws:
IllegalArgumentException - if the supplied directory has no project.xml
Method Detail

generateBuildScriptFromStylesheet

public void generateBuildScriptFromStylesheet(String path,
                                              URL stylesheet)
                                       throws IOException,
                                              IllegalStateException
Create build.xml or nbproject/build-impl.xml from project.xml plus a supplied XSLT stylesheet. This is the recommended way to create the build scripts from project metadata.

You may wish to first check getBuildScriptState(java.lang.String, java.net.URL) to decide whether you really want to overwrite an existing build script. Typically if you find FLAG_MODIFIED you should not overwrite it; or ask for confirmation first; or make a backup. Of course if you find neither of FLAG_OLD_STYLESHEET nor FLAG_OLD_PROJECT_XML then there is no reason to overwrite the script to begin with.

Acquires write access.

Parameters:
path - a project-relative file path such as BUILD_XML_PATH or BUILD_IMPL_XML_PATH
stylesheet - a URL to an XSLT stylesheet accepting project.xml as input and producing the build script as output
Throws:
IOException - if transforming or writing the output failed
IllegalStateException - if the project was modified (and not being saved)

getBuildScriptState

public int getBuildScriptState(String path,
                               URL stylesheet)
                        throws IllegalStateException
Find what state a build script is in. This may be used by a project type provider to decide whether to create or overwrite it, and whether to produce a backup in the latter case. Various abnormal conditions are detected: FLAG_MISSING, FLAG_MODIFIED, FLAG_OLD_PROJECT_XML, FLAG_OLD_STYLESHEET, and FLAG_UNKNOWN.

Currently FLAG_MODIFIED, FLAG_OLD_STYLESHEET, and FLAG_OLD_PROJECT_XML are detected by computing a CRC-32 of the script when it is created, as well as the CRC-32s of the stylesheet and project.xml. These CRCs are stored in a special file nbproject/genfiles.properties. The CRCs are based on the textual contents of the files (so even changed to whitespace etc. are considered changes), but are independent of platform newline conventions (since e.g. CVS will by default replace \n with \r\n when checking out on Windows). Changes to external files included into project.xml or the stylesheet (e.g. using XSLT's import facility) are not detected.

If there is some kind of I/O error reading any files, FLAG_UNKNOWN is returned (in conjunction with FLAG_MODIFIED, FLAG_OLD_STYLESHEET, and FLAG_OLD_PROJECT_XML to be safe).

Acquires read access.

Parameters:
path - a project-relative path such as BUILD_XML_PATH or BUILD_IMPL_XML_PATH
stylesheet - a URL to an XSLT stylesheet accepting project.xml as input and producing the build script as output (should match that given to generateBuildScriptFromStylesheet(java.lang.String, java.net.URL))
Returns:
a bitwise OR of various flags, or 0 if the script is present on disk and fully up-to-date
Throws:
IllegalStateException - if the project was modified

refreshBuildScript

public boolean refreshBuildScript(String path,
                                  URL stylesheet,
                                  boolean checkForProjectXmlModified)
                           throws IOException,
                                  IllegalStateException
Convenience method to refresh a build script if it can and should be.

If the script is not modified, and it is either missing, or the flag checkForProjectXmlModified is false, or it is out of date with respect to either project.xml or the stylesheet (or both), it is (re-)generated.

Acquires write access.

Typical usage from ProjectXmlSavedHook.projectXmlSaved() is to call this method for both BUILD_XML_PATH and BUILD_IMPL_XML_PATH with the appropriate stylesheets and with checkForProjectXmlModified false (the script is certainly out of date relative to project.xml). Typical usage from ProjectOpenedHook is to call this method for both scripts with the appropriate stylesheets and with checkForProjectXmlModified true.

Parameters:
path - a project-relative path such as BUILD_XML_PATH or BUILD_IMPL_XML_PATH
stylesheet - a URL to an XSLT stylesheet accepting project.xml as input and producing the build script as output
checkForProjectXmlModified - true if it is necessary to check whether the script is out of date with respect to project.xml and/or the stylesheet
Returns:
true if the script was in fact regenerated
Throws:
IOException - if transforming or writing the output failed
IllegalStateException - if the project was modified

org.netbeans.modules.project.ant/1 1.12.22

Built on July 11 2007.  |  Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.