org.netbeans.spi.project.support.ant

Class GeneratedFilesHelper

java.lang.Object

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

Fields

Modifier and Type	Field and Description
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 GeneratedFilesHelper.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

Constructors

Constructor and Description
GeneratedFilesHelper(AntProjectHelper h) Create a helper based on the supplied project helper handle.
GeneratedFilesHelper(AntProjectHelper h, AntBuildExtender ex) Create a helper based on the supplied project helper handle.
GeneratedFilesHelper(FileObject d) Create a helper based only on a project directory.

Method Summary

Modifier and Type	Method and Description
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:

GeneratedFilesHelper.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 GeneratedFilesHelper.generateBuildScriptFromStylesheet(java.lang.String, java.net.URL).

Probably this means it was edited by the user.

See Also:

GeneratedFilesHelper.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:

GeneratedFilesHelper.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).

Since org.netbeans.modules.project.ant/1 1.28, the code takes extra steps to prevent "seesawing", or overwriting a script generated by a new stylesheet when using an old stylesheet: the CRC of the stylesheet is augmented wherever possible with the specification version of the module containing that stylesheet.

See Also:

GeneratedFilesHelper.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 GeneratedFilesHelper.FLAG_MISSING but when set also sets GeneratedFilesHelper.FLAG_MODIFIED, GeneratedFilesHelper.FLAG_OLD_STYLESHEET, and GeneratedFilesHelper.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:

GeneratedFilesHelper.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(AntProjectHelper h,
                            AntBuildExtender ex)

Create a helper based on the supplied project helper handle. The created instance is capable of extending the generated files with 3rd party content.

Parameters:

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

ex - build extensibility support

Since:

org.netbeans.modules.project.ant 1.16

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.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

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 GeneratedFilesHelper.getBuildScriptState(java.lang.String, java.net.URL) to decide whether you really want to overwrite an existing build script. Typically if you find GeneratedFilesHelper.FLAG_MODIFIED you should not overwrite it; or ask for confirmation first; or make a backup. Of course if you find neither of GeneratedFilesHelper.FLAG_OLD_STYLESHEET nor GeneratedFilesHelper.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 GeneratedFilesHelper.BUILD_XML_PATH or GeneratedFilesHelper.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

getBuildScriptState

public int getBuildScriptState(String path,
                               URL stylesheet)

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: GeneratedFilesHelper.FLAG_MISSING, GeneratedFilesHelper.FLAG_MODIFIED, GeneratedFilesHelper.FLAG_OLD_PROJECT_XML, GeneratedFilesHelper.FLAG_OLD_STYLESHEET, and GeneratedFilesHelper.FLAG_UNKNOWN.

Currently GeneratedFilesHelper.FLAG_MODIFIED, GeneratedFilesHelper.FLAG_OLD_STYLESHEET, and GeneratedFilesHelper.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, GeneratedFilesHelper.FLAG_UNKNOWN is returned (in conjunction with GeneratedFilesHelper.FLAG_MODIFIED, GeneratedFilesHelper.FLAG_OLD_STYLESHEET, and GeneratedFilesHelper.FLAG_OLD_PROJECT_XML to be safe).

Acquires read access.

Parameters:

path - a project-relative path such as GeneratedFilesHelper.BUILD_XML_PATH or GeneratedFilesHelper.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 GeneratedFilesHelper.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

refreshBuildScript

public boolean refreshBuildScript(String path,
                                  URL stylesheet,
                                  boolean checkForProjectXmlModified)
                           throws IOException

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 GeneratedFilesHelper.BUILD_XML_PATH and GeneratedFilesHelper.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.projectOpened() is to call this method for both scripts with the appropriate stylesheets and with checkForProjectXmlModified true.

Parameters:

path - a project-relative path such as GeneratedFilesHelper.BUILD_XML_PATH or GeneratedFilesHelper.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