org.netbeans.api.templates

Class FileBuilder

java.lang.Object

org.netbeans.api.templates.FileBuilder

public final class FileBuilder
extends Object

Fluent interface for file creation. The Builder is first parametrized. After everything is set up, call FileBuilder.build() to materialize the template using the supplied parameters/settings.

The create file(s) get names derived from the template and the existing target folder contents (so that the filenames do not conflict with existing files). A desired filename can be set up by FileBuilder.name(java.lang.String).

The file build request will be forwarded to CreateFromTemplateHandlers; if none CreateFromTemplateHandler.accept(org.netbeans.api.templates.CreateDescriptor)s the request, the default procedure takes place, depending on the #defaultMode setting (default: FileBuilder.Mode.COPY).

There are several values predefined:

• name - the created filename without extension
• nameAndExt - the created filename including the extension
• date - date of creation, printed in the default date format
• dateTime - Date object representing the creation time
• time - time of creation, printed in the default time format
• user - the user id of the user creating the file

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FileBuilder.Mode Determines the default procedure for copying the template in FileBuilder.createFromTemplate(org.openide.filesystems.FileObject, org.openide.filesystems.FileObject, java.lang.String, java.util.Map<java.lang.String, ?>, org.netbeans.api.templates.FileBuilder.Mode).

Field Summary

Fields

Modifier and Type	Field and Description
static String	ATTR_TEMPLATE_HANDLER A specific CreateFromTemplateHandler to be used with this particular template.
static String	ATTR_TEMPLATE_MERGE_FOLDERS A flag used by the default template processing to create files from template structures in existing folders rather than create unique folder names.
static String	ATTR_TEMPLATE_OPEN_FILE Marks file(s) in the template, that should be opened in the editor.

Constructor Summary

Constructors

Constructor and Description
FileBuilder(FileObject template, FileObject target) Creates a new FileBuilder for a specific template and target folder.

Method Summary

Modifier and Type	Method and Description
List<FileObject>	build() Creates the file(s) from template.
CreateDescriptor	createDescriptor(boolean collectAttributes) Creates a descriptor from the current Builder's state.
static FileObject	createFromTemplate(FileObject f, FileObject folder, String name, Map<String,?> attributes, FileBuilder.Mode defaultMode) Creates a new file based on the template.
FileBuilder	defaultMode(FileBuilder.Mode m) Specifies the behaviour to be used when no CreateFromTemplateHandler accepts the template.
static FileBuilder	fromDescriptor(CreateDescriptor desc) Creates a Builder based on the CreateDescriptor.
FileBuilder	name(String n) Sets the desired target file's name.
FileBuilder	param(String n, Object v) Adds a parameter to the template.
FileBuilder	useFormat(Format def) Uses the specified formatter for file creation.
FileBuilder	useLocale(Locale l) Specifies the locale to be used during file creation.
FileBuilder	useLookup(Lookup contextLookup) Use specific Lookup for creation.
FileBuilder	withParameters(Map<String,?> params) Includes parameters for the template.

Methods inherited from class java.lang.Object

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

Field Detail

ATTR_TEMPLATE_HANDLER

public static final String ATTR_TEMPLATE_HANDLER

A specific CreateFromTemplateHandler to be used with this particular template. If present on a template, will be used as a default. Still can be overriden by a lookup-registered registered CreateFromTemplateHandler.

Since:

1.23

See Also:

Constant Field Values

ATTR_TEMPLATE_MERGE_FOLDERS

public static final String ATTR_TEMPLATE_MERGE_FOLDERS

A flag used by the default template processing to create files from template structures in existing folders rather than create unique folder names. By default, folders in template will create unique folders on the disk, if the same-named folder already exists. The attribute, if defined, should have a boolean value true/false.

Since:

1.23

See Also:

Constant Field Values

ATTR_TEMPLATE_OPEN_FILE

public static final String ATTR_TEMPLATE_OPEN_FILE

Marks file(s) in the template, that should be opened in the editor. If the template file attribute is set to Boolean.TRUE, the template handler should the file created from the file template from the FileBuilder.build() method. Note the attribute serves as a hint, so the Handler may choose to ignore the instruction.

Since:

1.23

See Also:

Constant Field Values

Constructor Detail

FileBuilder

public FileBuilder(@NonNull
                   FileObject template,
                   @NonNull
                   FileObject target)

Creates a new FileBuilder for a specific template and target folder.

Parameters:

template - the template to use.

target - the target folder; must already exist.

Method Detail

fromDescriptor

@NonNull
public static FileBuilder fromDescriptor(@NonNull
                                                  CreateDescriptor desc)

Creates a Builder based on the CreateDescriptor. The FileBuilder inherits all parameters of the original CreateDescriptor. The client may change the attributes. The method may be useful when creating secondary files; for example target and all attributes are retained. During FileBuilder.build(), attributes may be redefined as needed for the additional file, just like in normal Builder operation.

The new FileBuilder instance is completely indepenent of the original Descriptor. If the CreateDescriptor supports additional properties in the future, using this method guarantees that they will be transferred to the FileBuilder copy.

Parameters:

desc - the original descriptor

Returns:

new FileBuilder

Since:

1.5

useLookup

public FileBuilder useLookup(Lookup contextLookup)

Use specific Lookup for creation. This allows to pass in additional parameters or services. A GUI-aware caller may, for example, add a ProgressHandle or a project ActionProgress interface to the lookup, in a hope that template handler will use service to report progress.

Parameters:

contextLookup - the Lookup passed to template creation subprocesses

Returns:

this FileBuilder instance.

Since:

1.23

useLocale

public FileBuilder useLocale(@NonNull
                             Locale l)

Specifies the locale to be used during file creation. The locale also applies to the standard parameters passed to the template (e.g. date and time representation).

Parameters:

l - the locale

Returns:

this FileBuilder instance.

name

public FileBuilder name(String n)

Sets the desired target file's name.

Parameters:

n - the name

Returns:

this FileBuilder instance

withParameters

public FileBuilder withParameters(@NullAllowed
                                  Map<String,?> params)

Includes parameters for the template. For backwards compatibility, special parameters CreateDescriptor.FREE_FILE_EXTENSION and CreateDescriptor.PREFORMATTED_TEMPLATE are processed and appropriate properties modified on the CreateDescriptor.

Parameters:

params - the string-value pairs

Returns:

this FileBuilder instance

param

public FileBuilder param(@NonNull
                         String n,
                         Object v)

Adds a parameter to the template. For backwards compatibility, special parameters CreateDescriptor.FREE_FILE_EXTENSION and CreateDescriptor.PREFORMATTED_TEMPLATE are processed and appropriate properties modified on the CreateDescriptor.

Parameters:

n - parameter name

v - the value

Returns:

this FileBuilder instance

defaultMode

public FileBuilder defaultMode(@NonNull
                               FileBuilder.Mode m)

Specifies the behaviour to be used when no CreateFromTemplateHandler accepts the template.

Parameters:

m - the default processing mode

Returns:

this FileBuilder instance

See Also:

for details

useFormat

public FileBuilder useFormat(@NonNull
                             Format def)

Uses the specified formatter for file creation. Also sets the default mode to FileBuilder.Mode.FORMAT. If the supplied Format instance happens to be a MapFormat, the templating code will pass parameters produced by CreateFromTemplateAttributes to the format when the target file contents is generated.

Parameters:

def - the format to use

Returns:

this FileBuilder instance

See Also:

for details on different modes

build

@CheckForNull
public List<FileObject> build()
                                     throws IOException

Creates the file(s) from template.

Returns:

list of created files. If some file is 'master' or otherwise of high importance and represents the file set, it should be placed first in the list.

Throws:

IOException - if the creation fails

createDescriptor

@NonNull
public CreateDescriptor createDescriptor(boolean collectAttributes)

Creates a descriptor from the current Builder's state. If `collectAttributes' is false, the descriptor will have no additional parameters set from CreateFromTemplateAttributes providers; the caller must process the providers, if it wishes to get additional attributes. The Descriptor can be used to collect information from attribute providers or manually trigger file creation in template handler.

The operation changes the FileBuilder state.

Parameters:

collectAttributes - if true, attribute providers are asked to add their attributes to the builder/descriptor.

Returns:

descriptor

Since:

1.5

createFromTemplate

@CheckForNull
public static FileObject createFromTemplate(@NonNull
                                                          FileObject f,
                                                          @NonNull
                                                          FileObject folder,
                                                          @NullAllowed
                                                          String name,
                                                          @NullAllowed
                                                          Map<String,?> attributes,
                                                          FileBuilder.Mode defaultMode)
                                                   throws IOException

Creates a new file based on the template. This convenience method is intended for easier migration of clients using DataLoader templating API before FileBuilder introduction. The method will collect parameters tied to the template using registered CreateFromTemplateAttributes providers, and will try to locate a willing CreateFromTemplateHandler that will create the target file. If no such handler exists, and the defaultCopy parameter is true, the file contents is just copied to the target location.

If the name parameter is null, the function attempts to compute a suitable name from the file.

The default copy algorithm uses the supplied FileBuilder.Mode.FORMAT to process tokens.

If the passed name is null, the implementation will pick a free name based on the template's own name (see FileUtil.findFreeFileName(org.openide.filesystems.FileObject, java.lang.String, java.lang.String)).

Parameters:

f - the template file

folder - the target folder, must exist

name - the desired name. If null, the implementation will choose the name.

attributes - values to apply on the template. May be null = no values.

defaultMode - the mode of operations to use

Returns:

The created file, or null if no creation handler is located.

Throws:

IOException - when an I/O operation fails