org.openide.filesystems.annotations
Class LayerBuilder

java.lang.Object
  org.openide.filesystems.annotations.LayerBuilder

public final class LayerBuilder
extends Object

Convenience class for generating fragments of an XML layer.

Since:

org.openide.filesystems 7.15

See Also:

LayerGeneratingProcessor.layer(javax.lang.model.element.Element...)

Nested Class Summary

class

LayerBuilder.File Builder for creating a single file entry.

Method Summary

static String	absolutizeResource(Element originatingElement, String resource) Allows a processor to accept relative resource paths.
LayerBuilder.File	file(String path) Adds a file to the layer.
LayerBuilder.File	folder(String path) Adds a folder to the layer.
LayerBuilder.File	instanceFile(String path, String name) Generates an instance file that is not initialized with an instance.
LayerBuilder.File	instanceFile(String path, String name, Annotation annotation, String annotationMethod) Generates an instance file that is not initialized with an instance.
LayerBuilder.File	instanceFile(String path, String name, Class<?> type) Generates an instance file whose InstanceCookie would load the associated class or method.
LayerBuilder.File	instanceFile(String path, String name, Class<?> type, Annotation annotation, String annotationMethod) Generates an instance file whose InstanceCookie would load the associated class or method.
LayerBuilder.File	shadowFile(String target, String folder, String name) Convenience method to create a shadow file (like a symbolic link).
FileObject	validateResource(String resource, Element originatingElement, Annotation annotation, String annotationMethod, boolean searchClasspath) Validates a resource named in an annotation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

file

public LayerBuilder.File file(String path)

Adds a file to the layer. You need to LayerBuilder.File.write() it in order to finalize the effect.

Parameters:

path - the full path to the desired file in resource format, e.g. "Menu/File/exit.instance"

Returns:

a file builder

folder

public LayerBuilder.File folder(String path)

Adds a folder to the layer. You need to LayerBuilder.File.write() it in order to finalize the effect.

Normally just using file(java.lang.String) suffices, since parent folders are created as needed, but you may use this method if you wish to create a folder (possibly with some attributes) without necessarily creating any children.

Parameters:

path - the full path to the desired folder in resource format, e.g. "Menu/File"

Returns:

a file builder

Since:

org.openide.filesystems 7.26

instanceFile

public LayerBuilder.File instanceFile(String path,
                                      String name,
                                      Class<?> type)
                               throws IllegalArgumentException,
                                      LayerGenerationException

Generates an instance file whose InstanceCookie would load the associated class or method. Useful for LayerGeneratingProcessors which define layer fragments which instantiate Java objects from the annotated code.

While you can pick a specific instance file name, if possible you should pass null for name as using the generated name will help avoid accidental name collisions between annotations.

Parameters:

path - path to folder of instance file, e.g. "Menu/File"

name - instance file basename, e.g. "my-menu-Item", or null to pick a name according to the element

type - a type to which the instance ought to be assignable, or null to skip this check

Returns:

an instance file (call LayerBuilder.File.write() to finalize)

Throws:

IllegalArgumentException - if the builder is not associated with exactly one class or method

LayerGenerationException - if the associated element would not be loadable as an instance of the specified type

instanceFile

public LayerBuilder.File instanceFile(String path,
                                      String name,
                                      Class<?> type,
                                      Annotation annotation,
                                      String annotationMethod)
                               throws IllegalArgumentException,
                                      LayerGenerationException

Generates an instance file whose InstanceCookie would load the associated class or method. Useful for LayerGeneratingProcessors which define layer fragments which instantiate Java objects from the annotated code.

While you can pick a specific instance file name, if possible you should pass null for name as using the generated name will help avoid accidental name collisions between annotations.

Parameters:

path - path to folder of instance file, e.g. "Menu/File"

name - instance file basename, e.g. "my-menu-Item", or null to pick a name according to the element

type - a type to which the instance ought to be assignable, or null to skip this check

annotation - as in LayerGenerationException.LayerGenerationException(String,Element,ProcessingEnvironment,Annotation,String)

annotationMethod - as in LayerGenerationException.LayerGenerationException(String,Element,ProcessingEnvironment,Annotation,String)

Returns:

an instance file (call LayerBuilder.File.write() to finalize)

Throws:

IllegalArgumentException - if the builder is not associated with exactly one class or method

LayerGenerationException - if the associated element would not be loadable as an instance of the specified type

Since:

7.50

instanceFile

public LayerBuilder.File instanceFile(String path,
                                      String name)
                               throws IllegalArgumentException,
                                      LayerGenerationException

Generates an instance file that is not initialized with an instance. Useful for LayerGeneratingProcessors which define layer fragments which indirectly instantiate Java objects from the annotated code via a generic factory method. Invoke the factory using LayerBuilder.File.methodvalue(java.lang.String, java.lang.String, java.lang.String) on instanceCreate and configure it with a LayerBuilder.File.instanceAttribute(java.lang.String, java.lang.Class) appropriate to the factory.

While you can pick a specific instance file name, if possible you should pass null for name as using the generated name will help avoid accidental name collisions between annotations.

Parameters:

path - path to folder of instance file, e.g. "Menu/File"

name - instance file basename, e.g. "my-menu-Item", or null to pick a name according to the element

Returns:

an instance file (call LayerBuilder.File.write() to finalize)

Throws:

IllegalArgumentException - if the builder is not associated with exactly one class or method

LayerGenerationException - if the associated element would not be loadable as an instance

Since:

org.openide.filesystems 7.27

instanceFile

public LayerBuilder.File instanceFile(String path,
                                      String name,
                                      Annotation annotation,
                                      String annotationMethod)
                               throws IllegalArgumentException,
                                      LayerGenerationException

Generates an instance file that is not initialized with an instance. Useful for LayerGeneratingProcessors which define layer fragments which indirectly instantiate Java objects from the annotated code via a generic factory method. Invoke the factory using LayerBuilder.File.methodvalue(java.lang.String, java.lang.String, java.lang.String) on instanceCreate and configure it with a LayerBuilder.File.instanceAttribute(java.lang.String, java.lang.Class) appropriate to the factory.

While you can pick a specific instance file name, if possible you should pass null for name as using the generated name will help avoid accidental name collisions between annotations.

Parameters:

path - path to folder of instance file, e.g. "Menu/File"

name - instance file basename, e.g. "my-menu-Item", or null to pick a name according to the element

annotation - as in LayerGenerationException.LayerGenerationException(String,Element,ProcessingEnvironment,Annotation,String)

annotationMethod - as in LayerGenerationException.LayerGenerationException(String,Element,ProcessingEnvironment,Annotation,String)

Returns:

an instance file (call LayerBuilder.File.write() to finalize)

Throws:

IllegalArgumentException - if the builder is not associated with exactly one class or method

LayerGenerationException - if the associated element would not be loadable as an instance

Since:

org.openide.filesystems 7.50

shadowFile

public LayerBuilder.File shadowFile(String target,
                                    String folder,
                                    String name)

Convenience method to create a shadow file (like a symbolic link).

While you can pick a specific shadow file name, if possible you should pass null for name as using the generated name will help avoid accidental name collisions between annotations.

Parameters:

target - the complete path to the original file (use LayerBuilder.File.getPath() if you just made it)

folder - the folder path in which to create the shadow, e.g. "Menu/File"

name - the basename of the shadow file sans extension, e.g. "my-Action", or null to pick a default

Returns:

a shadow file (call LayerBuilder.File.write() to finalize)

validateResource

public FileObject validateResource(String resource,
                                   Element originatingElement,
                                   Annotation annotation,
                                   String annotationMethod,
                                   boolean searchClasspath)
                            throws LayerGenerationException

Validates a resource named in an annotation.

Note that resources found in the binary classpath (if permitted) cannot actually be located when running inside javac on JDK 6 (see #196933 for discussion), in which case no exception is thrown but the return value may not permit FileObject.openInputStream(). AnnotationProcessorTestUtils.searchClasspathBroken should be used in unit tests affected by this bug.

Also remember that the binary compilation classpath for an Ant-based NetBeans module does not include non-public packages. (As of the 7.1 harness it does include non-classfile resources from public packages of module dependencies.) The processorpath does contain all of these but it is not consulted. The classpath for a Maven-based module does contain all resources from dependencies.

Parameters:

resource - an absolute resource path with no leading slash (perhaps the output of absolutizeResource(javax.lang.model.element.Element, java.lang.String))

originatingElement - the annotated element; used both for error reporting, and (optionally) for its package

annotation - as in LayerGenerationException.LayerGenerationException(String,Element,ProcessingEnvironment,Annotation,String)

annotationMethod - as in LayerGenerationException.LayerGenerationException(String,Element,ProcessingEnvironment,Annotation,String)

searchClasspath - true to search in the binary classpath and not just source path (see caveat about JDK 6)

Returns:

the content of the resource, for further validation

Throws:

LayerGenerationException - if no such resource can be found

Since:

7.51

absolutizeResource

public static String absolutizeResource(Element originatingElement,
                                        String resource)
                                 throws LayerGenerationException

Allows a processor to accept relative resource paths. For example, to produce the output value net/nowhere/lib/icon.png given an element in the package net.nowhere.app, the following inputs are permitted:

• ../lib/icon.png
• /net/nowhere/lib/icon.png

Parameters:

originatingElement - the annotated element, used for its package

resource - a possibly relative resource path

Returns:

an absolute resource path (with no leading slash)

Throws:

LayerGenerationException - in case the resource path is malformed

Since:

7.51