<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE api-answers PUBLIC "-//NetBeans//DTD Arch Answers//EN" "../nbbuild/antsrc/org/netbeans/nbbuild/Arch.dtd" [

  <!ENTITY api-questions SYSTEM "../nbbuild/antsrc/org/netbeans/nbbuild/Arch-api-questions.xml">

]>

<api-answers

  question-version="1.29"

  author="sdedic@netbeans.org"

>

  &api-questions;

 <answer id="arch-overall">

  <p>

      API allows to create new files based on templates. Scripting engines can be specified for

      processing the template, or custom Handlers may be registered to process certain templates.

  </p>

  <p>

      A template can use places substituable with parameter values; certain well-known parameters are 

      predefined, if the caller does not provide its custom values.

  </p>

 </answer>

 <answer id="arch-quality">

  <p>

   The feature will be fully covered by unit tests.

  </p>

 </answer>

 <answer id="arch-time">

  <p>

   October 2014

  </p>

 </answer>

<!--

        <question id="arch-usecases" when="init">

            <hint>

                Content of this answer will be displayed as part of page at

                http://www.netbeans.org/download/dev/javadoc/usecases.html 

                You can use tags <usecase name="name> regular html description </usecase>

                and if you want to use an URL you can prefix if with @TOP@ to begin

                at the root of your javadoc

            </hint>

            Describe the main <a href="http://wiki.netbeans.org/API_Design#The_Importance_of_Being_Use_Case_Oriented">

            use cases</a> of the new API. Who will use it under

            what circumstances? What kind of code would typically need to be written

            to use the module?

        </question>

-->

 <answer id="arch-usecases">

     <usecase id="template" name="Use boilerplates">

         <p>

             An existing file can be used as a boilerplate for creation of a new file.

             The boiler plate can contain necessary skeleton, comments, content. As the

             boilerplate resides on config filesystem, it is also customizable by the user

             and the user can eventually develop custom templates.

         </p>

         <p>

             In previous NetBeans versions, templating system was built into 

             <api name="DataSystemsAPI" category="official" group="java" type="export" 

                url="@org-openide-loaders@/index.html"/>.

         </p>

     </usecase>

     <usecase id="templateHandler" name="Custom template handlers">

        <p>

            Often many people require ability to create a "clever" template - e.g.

            write piece of simple text and at the time of its 

            <a href="@TOP@/org/netbeans/api/templates/TemplateUtils.html#createFromTemplate(org.openide.filesystems.FileObject, org.openide.filesystems.FileObject, java.lang.String, java.util.Map, org.netbeans.api.templates.FileBuilder.Mode)">

                processing

            </a> 

            do some advanced changes to it using either 

            <a name="script">scripting or templating</a> languages.

        </p>

        <p>

            This traditionally used to be a bit complicated task (hacking into DataObject implementation), however since 

            version 6.1 there are interface in 

            <api name="org.openide.loaders.CreateFromTemplateHandler" category="deprecated" group="lookup" type="export"

                 url="@org-openide-loaders@/org/openide/loaders/CreateFromTemplateHandler.html">

                DataSystem API

            </api>

            and finally

            <api name="org.netbeans.api.templates.CreateFromTemplateHandler" category="official" group="lookup" type="export"

             url="@TOP@/org/netbeans/api/templates/CreateFromTemplateHandler.html">

                that can be registered as a services in a lookup and it is reponsible

                for handling the whole copy of the template file(s) to the destination

                folder.

            </api>

        </p>

     </usecase>

     <usecase id="templateAttributes" name="Custom attributes for processing">

         <p>

            Runtime or project-related values may be supplied by 

           <api name="org.openide.loaders.CreateFromTemplateAttributes" category="official" group="lookup" type="export"

           url="@TOP@/org/netbeans/api/templates/CreateFromTemplateAttributes.html">

               that can be registered as a services in a lookup and it is reponsible

               for providing "hints" - e.g. map mapping strings to various objects.

           </api> and these interfaces allow anyone to extend the behaviour during

           creation of new files.

         </p>

         <p>

             The <a href="@TOP@/org/netbeans/api/templates/CreateFromTemplateAttributes.html">CreateFromTemplateAttribute</a> implementation

             knows which template is being used, where the outcome should be placed, so it can derive appropriate values for both 

             the template and the target location.

         </p>

     </usecase>

     <usecase id="script" name="Using Scripting and Templating Languages" >

        <p>

        There is a built in support for scripting languages in

        the standard NetBeans IDE. If a template is annotated with

        <api name="javax.script.ScriptEngine" category="official" group="property" type="export">

            a property that can be associated to templates that either should

            return real instance of <code>ScriptEngine</code> interface or

            a <code>String</code> name of the engine that is then used to

            search for it in the <code>javax.script.ScriptEngineManager</code>.

            Usually the <a href="http://freemarker.sourceforge.net/">freemarker</a> engine is the one that is 

            supported by the NetBeans IDE - if your module wants to use it

            then include a token dependency <code>OpenIDE-Module-Needs: javax.script.ScriptEngine.freemarker</code>

            in your manifest file (also accessible through project customizer GUI)

            to indicate to the system that you need it.

        </api>

        then the scripting engine is then used to process the template and

        generate the output file. While running the engine one can rely

        on few predefined properties:

        </p>

        <ul>

            <li><api name="name" category="stable" group="property" type="export"> contains the name of the <a href="@org-openide-loaders@/org/openide/loaders/DataObject.html">DataObject</a> that is being created</api></li>

            <li><api name="user" category="stable" group="property" type="export"> contains the name the user</api></li>

            <li><api name="nameAndExt" category="stable" group="property" type="export"> contains the name and extension of the file that is being created</api></li>

            <li><api name="date" category="stable" group="property" type="export"> contains <code>String</code> representing the current day like <code>23. 3. 2007</code></api></li>

            <li><api name="time" category="stable" group="property" type="export"> contains <code>String</code> the current time like <code>17:18:30</code></api></li>

            <li><api name="dateTime" category="stable" group="property" type="export"> contains <code>java.util.Date</code> representing current data and time like</api></li>

            <li><api name="encoding" category="stable" group="property" type="export"> contains <code>String</code> the file encoding of the template instance</api></li>

        </ul>

        <p>

        Other properties can indeed be provided by

        <a href="@TOP@/org/netbeans/api/templates/CreateFromTemplateAttributes.html">CreateFromTemplateAttributes</a>s.

        After processing, the output is also sent to appropriate

        <code>org.openide.text.IndentEngine</code> associated

        with the mime type of the template, for formating.

        </p>

        <p style="margin-left: 0.2in; margin-right: 0.2in; margin-top: 0.2in; margin-bottom: 0.2in; border: 1.00pt solid #9999cc; padding: 0.1in; color: #666699">

            <b>Smart Templating Quick How-To</b>

            <br/>

            First of all create a file in your module layer located somewhere

            under the <code>Templates/</code> folder. Make it a template by

            adding <attr name="template" boolvalue="true"/>. Associate

            this template with a scripting language, for example by

            <attr name="javax.script.ScriptEngine" stringvalue="freemarker"/>.

            Now make sure that the scripting language integration is also available

            by requesting a token in standard format, for freemarker just put

            <code>OpenIDE-Module-Needs: javax.script.ScriptEngine.freemarker</code>

            in your manifest. This tells the NetBeans module system that a 

            module providing integration with such scripting engine has to be 

            enabled. Now you can use regular script language tags inside of

            your template file. When you write your <code>instantiate</code>

            method in your wizard, you can create a Map<String,Object> and

            fill it with parameters collected from your wizard and then pass it 

            to

            <a href="@org-openide-loaders@/org/openide/loaders/DataObject.html#createFromTemplate(org.openide.loaders.DataFolder,%20java.lang.String,%20java.util.Map)">                

                createFromTemplate(targetFolder, targetName, mapWithParameters)

            </a>. This will invoke the scripting language and make the 

            <code>mapWithParameters</code> values available to it. Beyond this 

            there is few standard parameters predefined including <code>name</code>, <code>user</code>, <code>date</code>, <code>time</code>, etc.

            and also additional parameters are collected from all registered

            <a href="@org-openide-loaders@/org/openide/loaders/CreateFromTemplateAttributesProvider.html">CreateFromTemplateAttributesProvider</a>s.

        </p>

     </usecase>

    <usecase id="file-sets" name="Create sets of files" >

        <p>

            A <a href="@TOP@/org/netbeans/api/templates/CreateFromTemplateHandler.html">CreateFromTemplateHandler</a>

            should be able to create multiple files, one of them <i>important</i> so it will open after user 

            initiates the creation action. The template of set of related files may be represented by a folder with

            a handler attached, and the operation deploys multiple files in the target directory.

        </p>

    </usecase>

 </answer>

 <answer id="arch-what">

  <p>

   This utility standardizes the process to use files as blueprints to create new files.

  </p>

 </answer>

 <answer id="arch-where">

  <defaultanswer generate='here' />

 </answer>

 <answer id="compat-deprecation">

  <p>

   This module replaces some implementation in DataSystem APIs so the implementation

    is usable even without DataSystems API itself. DataSystems API will use this

    library.

  </p>

 </answer>

 <answer id="compat-i18n">

  <p>

   Yes.

  </p>

 </answer>

 <answer id="compat-standards">

  <p>

   No.

  </p>

 </answer>

 <answer id="compat-version">

  <p>

   Yes.

  </p>

 </answer>

 <answer id="dep-jre">

  <p>

   Requires JRE 7, for implementation reasons (AutoCloseable).

  </p>

 </answer>

 <answer id="dep-jrejdk">

  <p>

   JRE

  </p>

 </answer>

 <answer id="dep-nb">

  <defaultanswer generate='here' />

 </answer>

 <answer id="dep-non-nb">

  <p>

   None.

  </p>

 </answer>

 <answer id="dep-platform">

  <p>

   No native platform dependencies.

  </p>

 </answer>

 <answer id="deploy-dependencies">

  <p>

   No specific deploy dependencies.

  </p>

 </answer>

 <answer id="deploy-jar">

  <p>

   JARs only.

  </p>

 </answer>

 <answer id="deploy-nbm">

  <p>

   Yes.

  </p>

 </answer>

 <answer id="deploy-packages">

  <p>

   Yes, except API.

  </p>

 </answer>

 <answer id="deploy-shared">

  <p>

   Anywhere.

  </p>

 </answer>

 <answer id="exec-ant-tasks">

  <p>

   No.

  </p>

 </answer>

 <answer id="exec-classloader">

  <p>

   No.

  </p>

 </answer>

 <answer id="exec-component">

  <p>

   No.

  </p>

 </answer>

 <answer id="exec-introspection">

  <p>

   No.

  </p>

 </answer>

 <answer id="exec-privateaccess">

  <p>

   No.

  </p>

 </answer>

 <answer id="exec-process">

  <p>

   No.

  </p>

 </answer>

 <answer id="exec-property">

  <p>

    <api name="org.netbeans.api.templates.IndentEngine" category="friend" group="property" type="export">

    A special ScriptEngine type is required to perform indentation on the produced sources.

    The ScriptEngine must provide a name "<code>org.netbeans.api.templates.IndentEngine</code>". 

    The only attribute property passed to the ScriptContext is <code>mimeType</code> of the 

    text being formatted.

    </api>

  </p>

 </answer>

 <answer id="exec-reflection">

  <p>

   No.

  </p>

 </answer>

 <answer id="exec-threading">

  <p>

   Yes.

  </p>

 </answer>

 <answer id="format-clipboard">

  <p>

   None.

  </p>

 </answer>

 <answer id="format-dnd">

  <p>

   None.

  </p>

 </answer>

 <answer id="format-types">

  <p>

   None.

  </p>

 </answer>

 <answer id="lookup-lookup">

  <p>

      Yes, looks up <a href="@TOP@/org/netbeans/api/templates/CreateFromTemplateAttributes.html">CreateFromTemplateAttributes</a>

      and <a href="@TOP@/org/netbeans/api/templates/CreateFromTemplateHandler.html">CreateFromTemplateHandler</a>.

  </p>

 </answer>

 <answer id="lookup-register">

  <p>

      Registers handler, which integrates scripting engines using <code>javax.script</code> API. Provides an annotation

      processor, so it is easy to register - see 

      <a href="@TOP@/org/netbeans/api/templates/TemplateRegistration.html">TemplateRegistration</a> annotation.

  </p>

 </answer>

 <answer id="lookup-remove">

  <p>

   No.

  </p>

 </answer>

 <answer id="perf-exit">

  <p>

   No.

  </p>

 </answer>

 <answer id="perf-huge_dialogs">

  <p>

   No UI.

  </p>

 </answer>

 <answer id="perf-limit">

  <p>

   Files are processed in-memory in documents; practical limits are imposed

    by the platform's Document implementation.

  </p>

 </answer>

 <answer id="perf-mem">

  <p>

   See 'perf-limit'

  </p>

 </answer>

 <answer id="perf-menus">

  <p>

   No UI.

  </p>

 </answer>

 <answer id="perf-progress">

  <p>

   No.

  </p>

 </answer>

 <answer id="perf-scale">

  <p>

   XXX no answer for perf-scale

  </p>

 </answer>

 <answer id="perf-spi">

  <p>

   No practical enforcement.

  </p>

 </answer>

 <answer id="perf-startup">

  <p>

   No.

  </p>

 </answer>

 <answer id="perf-wakeup">

  <p>

   No.

  </p>

 </answer>

 <answer id="resources-file">

  <p>

   No.

  </p>

 </answer>

 <answer id="resources-layer">

  <p>

   No.

  </p>

 </answer>

 <answer id="resources-mask">

  <p>

   No.

  </p>

 </answer>

 <answer id="resources-preferences">

  <p>

   No.

  </p>

 </answer>

 <answer id="resources-read">

  <p>

   No.

  </p>

 </answer>

 <answer id="security-grant">

  <p>

   No.

  </p>

 </answer>

 <answer id="security-policy">

  <p>

   No.

  </p>

 </answer>

</api-answers>

<?xml version="1.0" encoding="UTF-8"?>

<project basedir="." default="netbeans" name="api.templates">

    <description>Builds, tests, and runs the project org.netbeans.api.templates</description>

    <import file="../nbbuild/templates/projectized.xml"/>

</project>

Manifest-Version: 1.0

AutoUpdate-Show-In-Client: false

OpenIDE-Module: org.netbeans.api.templates

OpenIDE-Module-Localizing-Bundle: org/netbeans/modules/templates/Bundle.properties

OpenIDE-Module-Specification-Version: 1.0

OpenIDE-Module-Recommends: org.netbeans.templates.IndentEngine

javac.source=1.7

javac.compilerargs=-Xlint -Xlint:-serial

javadoc.arch=${basedir}/arch.xml

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://www.netbeans.org/ns/project/1">

    <type>org.netbeans.modules.apisupport.project</type>

    <configuration>

        <data xmlns="http://www.netbeans.org/ns/nb-module-project/3">

            <code-name-base>org.netbeans.api.templates</code-name-base>

            <module-dependencies>

                <dependency>

                    <code-name-base>org.netbeans.api.annotations.common</code-name-base>

                    <build-prerequisite/>

                    <compile-dependency/>

                    <run-dependency>

                        <release-version>1</release-version>

                        <specification-version>1.25</specification-version>

                    </run-dependency>

                </dependency>

                <dependency>

                    <code-name-base>org.netbeans.modules.nbjunit</code-name-base>

                    <build-prerequisite/>

                    <compile-dependency/>

                    <run-dependency>

                        <release-version>1</release-version>

                        <specification-version>1.85</specification-version>

                    </run-dependency>

                </dependency>

                <dependency>

                    <code-name-base>org.netbeans.modules.queries</code-name-base>

                    <build-prerequisite/>

                    <compile-dependency/>

                    <run-dependency>

                        <release-version>1</release-version>

                        <specification-version>1.40</specification-version>

                    </run-dependency>

                </dependency>

                <dependency>

                    <code-name-base>org.openide.filesystems</code-name-base>

                    <build-prerequisite/>

                    <compile-dependency/>

                    <run-dependency>

                        <specification-version>9.1</specification-version>

                    </run-dependency>

                </dependency>

                <dependency>

                    <code-name-base>org.openide.util</code-name-base>

                    <build-prerequisite/>

                    <compile-dependency/>

                    <run-dependency>

                        <specification-version>9.3</specification-version>

                    </run-dependency>

                </dependency>

                <dependency>

                    <code-name-base>org.openide.util.lookup</code-name-base>

                    <build-prerequisite/>

                    <compile-dependency/>

                    <run-dependency>

                        <specification-version>8.26</specification-version>

                    </run-dependency>

                </dependency>

            </module-dependencies>

            <test-dependencies>

                <test-type>

                    <name>unit</name>

                    <test-dependency>

                        <code-name-base>org.netbeans.libs.freemarker</code-name-base>

                    </test-dependency>

                    <test-dependency>

                        <code-name-base>org.netbeans.modules.editor.mimelookup</code-name-base>

                        <compile-dependency/>

                        <test/>

                    </test-dependency>

                    <test-dependency>

                        <code-name-base>org.netbeans.modules.editor.mimelookup.impl</code-name-base>

                    </test-dependency>

                    <test-dependency>

                        <code-name-base>org.netbeans.modules.masterfs</code-name-base>

                    </test-dependency>

                    <test-dependency>

                        <code-name-base>org.openide.awt</code-name-base>

                    </test-dependency>

                    <test-dependency>

                        <code-name-base>org.openide.dialogs</code-name-base>

                        <compile-dependency/>

                    </test-dependency>

                    <test-dependency>

                        <code-name-base>org.openide.loaders</code-name-base>

                        <compile-dependency/>

                    </test-dependency>

                    <test-dependency>

                        <code-name-base>org.openide.nodes</code-name-base>

                        <compile-dependency/>

                    </test-dependency>

                    <test-dependency>

                        <code-name-base>org.openide.util.lookup</code-name-base>

                        <compile-dependency/>

                        <test/>

                    </test-dependency>

                    <test-dependency>

                        <code-name-base>org.openide.modules</code-name-base>

                    </test-dependency>

                    <test-dependency>

                        <code-name-base>org.netbeans.modules.masterfs</code-name-base>

                    </test-dependency>

                    <test-dependency>

                        <code-name-base>org.netbeans.modules.editor.document</code-name-base>

                        <compile-dependency/>

                        <recursive/>

                    </test-dependency>

                    <test-dependency>

                        <code-name-base>org.netbeans.modules.editor.indent</code-name-base>

                        <compile-dependency/>

                        <recursive/>

                    </test-dependency>

                    <test-dependency>

                        <code-name-base>org.openide.util.ui</code-name-base>

                        <compile-dependency/>

                    </test-dependency>

                    <test-dependency>

                        <code-name-base>org.netbeans.modules.editor.lib</code-name-base>

                        <compile-dependency/>

                    </test-dependency>

                </test-type>

            </test-dependencies>

            <public-packages>

                <package>org.netbeans.api.templates</package>

                <package>org.openide.loaders</package>

            </public-packages>

        </data>

    </configuration>

</project>

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2014 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2014 Sun Microsystems, Inc.

 */

package org.netbeans.api.templates;

import java.util.Collections;

import java.util.Locale;

import java.util.Map;

import org.netbeans.api.annotations.common.CheckForNull;

import org.netbeans.api.annotations.common.NonNull;

import org.openide.filesystems.FileObject;

/**

 * Describes file creation request. The description is produced by the

 * {@link FileBuilder} and is sent out to

 * {@link CreateFromTemplateAttribute} and {@link CreateFromTemplateHandler} 

 * SPIs as the context for their work.

 * <p/>

 * The class is not thread-safe. Do not access the descriptor from a thread other

 * than executing the {@link CreateFromTemplateHandler} callbacks.

 * 

 * @author sdedic

 */

public final class CreateDescriptor {

    private final FileObject      template;

    private final FileObject      target;

    /**

     * The originally specified name for the new file

     */

    @SuppressWarnings("PackageVisibleField")

    String                name;

    /**

     * The proposed name - either specified, or computed

     */

    @SuppressWarnings("PackageVisibleField")

    String                proposedName;

    /**

     * Template parameters

     */

    @SuppressWarnings("PackageVisibleField")

    Map<String, Object>   parameters;

    /**

     * The locale used for file creation

     */

    Locale                locale = Locale.getDefault();

    /* package private */

    CreateDescriptor(FileObject template, FileObject target) {

        this.template = template;

        this.target = target;

    }

    /**

     * @return the template file

     */

    public @NonNull FileObject getTemplate() {

        return template;

    }

    /**

     * @return the target folder

     */

    public @NonNull FileObject getTarget() {

        return target;

    }

    /**

     * Provides the desired name for the created file. {@code null} can be

     * returned to indicate the filename should be derived automatically.

     * @return name for the created file

     */

    public @CheckForNull String getName() {

        return name;

    }

    /**

     * Provides a name proposed for the file. If the caller specified the name,

     * the value will be the same as {@link #getName}. A handler is encouraged

     * to use the proposed name if it does not require a certain naming scheme.

     * @return proposed name for the created file

     */

    public @NonNull String getProposedName() {

        return proposedName != null ? proposedName : name;

    }

    /**

     * Provides the desired user locale for creating the template

     * @return locale

     */

    public @NonNull Locale getLocale() {

        return locale;

    }

    /**

     * Provides value for the named key. Values are originally provided by

     * the caller, or the template itself; values can be provided also by

     * {@link CreateFromTemplateAttribute} implementors.

     * 

     * @param <T> value type.

     * @param n key name

     * @return named value or {@code null} if the key does not exist/has no value.

     */

    @CheckForNull

    public <T> T getValue(String n) {

        return (T)parameters.get(n);

    }

    /**

     * Provides access to the complete parameter map.

     * @return readonly string-value map.

     */

    public @NonNull Map<String, Object> getParameters() {

        return parameters == null ? Collections.<String, Object>emptyMap() : 

                Collections.unmodifiableMap(parameters);

    }

}

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 1997-2010 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * Contributor(s):

 *

 * The Original Software is NetBeans. The Initial Developer of the Original

 * Software is Sun Microsystems, Inc.

 *

 * Portions Copyrighted 2007 Sun Microsystems, Inc.

 */

package org.netbeans.api.templates;

import java.util.Map;

/** This is an interface for <q>smart templating</q>.

 * Implementations of this class can be registered in the global {@link org.openide.util.Lookup}

 * and allows anyone provide additional parameters to each {@link CreateFromTemplateHandler}s

 * when a template is instantiating.

 * <p/>

 * Implementations are called in the order of appearance in Lookup. The positions less than 0 are

 * reserved for the platform. Implementations called later can see and override

 * values defined by earlier CreateFromTemplateAttributes.

 * <p/>

 * Read more in the <a href="@TOP@/architecture-summary.html#script">howto document</a>.

 * <p/>

 * This interface supersedes {@code CreateFromTemplateAttributesProvider} in {@code openide.loaders} module.

 * 

 * @author Svata Dedic

 */

public interface CreateFromTemplateAttributes {

    /** Called when a template is about to be instantiated to provide additional

     * values to the {@link CreateFromTemplateHandler} that will handle the 

     * template instantiation.

     * <p/>

     * If the returned Map defines the same value as some {@link CreateFromTemplateAttributes} registered

     * earlier, the Map's value takes precedence. Parameters supplied by the {@link FileBuilder} cannot be

     * overriden.

     * 

     * @param desc the creation request

     * @return map of named objects, or null

     */

    Map<String,?> attributesFor(CreateDescriptor desc);

}

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 1997-2010 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * Contributor(s):

 *

 * The Original Software is NetBeans. The Initial Developer of the Original

 * Software is Sun Microsystems, Inc.

 *

 * Portions Copyrighted 2007 Sun Microsystems, Inc.

 */

package org.netbeans.api.templates;

import java.io.IOException;

import java.util.List;

import org.netbeans.api.annotations.common.NonNull;

import org.openide.filesystems.FileObject;

/** This is an interface for <i>smart templating</i> that allows

 * any module to intercept calls to {@link DataObject#createFromTemplate} 

 * and handle them themselves. The NetBeans IDE provides default

 * implementation that allows use of Freemarker templating engine.

 * Read more in the <a href="@TOP@/architecture-summary.html#script">howto document</a>.

 *

 * @author Jaroslav Tulach

 * @author Svatopluk Dedic

 */

public abstract class CreateFromTemplateHandler {

    /** Method that allows a handler to reject a file. If all handlers

     * reject a file, regular processing defined in {@link DataObject#handleCreateFromTemplate}

     * is going to take place.

     * 

     * @param desc

     * @return true if this handler wants to handle the createFromTemplate operation

     */

    protected abstract boolean accept(CreateDescriptor desc);

    /** Handles the creation of new files. The Handler may create one or more files. The 

     * files should be ordered so that the "important" file (i.e. the one which is then presented

     * to the user etc) is ordered first in the list.

     * 

     * @param desc command objects that describes the file creation request

     * @return the newly create file

     * @throws IOException if something goes wrong with I/O

     */

    protected abstract @NonNull List<FileObject> createFromTemplate(

            CreateDescriptor    desc

    ) throws IOException;

    /**

     * Parameter to enable free file extension mode.

     * By default, the extension of the newly created file will be inherited

     * from the template. But if {@link #createFromTemplate} is called with this

     * parameter set to {@link Boolean#TRUE}

     * (such as from {@link DataObject#createFromTemplate(DataFolder,String,Map)}),

     * and the file name already seems to

     * include an extension (<samp>*.*</samp>), the handler should not append

     * any extension from the template.

     * @since org.openide.loaders 7.16

     * @see <a href="@org-netbeans-modules-projectuiapi@/org/netbeans/spi/project/ui/templates/support/Templates.SimpleTargetChooserBuilder.html#freeFileExtension()"><code>Templates.SimpleTargetChooserBuilder.freeFileExtension</code></a>

     */

    public static final String FREE_FILE_EXTENSION = "freeFileExtension"; // NOI18N

}

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2014 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2014 Sun Microsystems, Inc.

 */

package org.netbeans.api.templates;

import java.io.BufferedReader;

import java.io.IOException;

import java.io.InputStream;

import java.io.InputStreamReader;

import java.io.OutputStream;

import java.io.OutputStreamWriter;

import java.io.Reader;

import java.io.StringReader;

import java.io.StringWriter;

import java.io.Writer;

import java.nio.charset.Charset;

import java.text.Format;

import java.util.Collections;

import java.util.Date;

import java.util.HashMap;

import java.util.List;

import java.util.Map;

import javax.script.ScriptContext;

import javax.script.ScriptEngine;

import javax.script.ScriptException;

import org.netbeans.api.queries.FileEncodingQuery;

import org.netbeans.modules.templates.ScriptingCreateFromTemplateHandler;

import org.openide.filesystems.FileLock;

import org.openide.filesystems.FileObject;

import org.openide.filesystems.FileUtil;

import org.openide.util.Lookup;

import org.openide.util.MapFormat;

import org.openide.util.Parameters;

/**

 *

 * @author sdedic

 */

final class CreateFromTemplateImpl {

    private static final String PROP_TEMPLATE = "template"; // NOI18N

    private static final String EA_PREFORMATTED = "org-netbeans-modules-java-preformattedSource"; // NOI18N

    private static final String NEWLINE = "\n"; // NOI18N

    private final FileBuilder builder;

    private final CreateDescriptor desc;

    private Map<String, ?> originalParams;

    private CreateFromTemplateImpl(FileBuilder builder) {

        this.builder = builder;

        this.desc = builder.getDescriptor();

    }

    static List<FileObject> build(FileBuilder flb) throws IOException {

        CreateFromTemplateImpl impl = new CreateFromTemplateImpl(flb);

        return impl.build();

    }

    List<FileObject> build() throws IOException {

        // side effects: replaces the map in CreateDescriptor

        try {

            FileObject f = desc.getTemplate();

            FileObject folder = desc.getTarget();

            FileBuilder.Mode defaultMode = null;

            Format frm = null;

            Parameters.notNull("f", f);

            Parameters.notNull("folder", folder);

            assert defaultMode != FileBuilder.Mode.FORMAT || frm != null : "Format must be provided for Mode.FORMAT";

            if (!folder.isFolder()) {

                throw new IllegalArgumentException("Not a folder: "  + folder);

            }

            // also modifies desc.getParameters, result not needed.

            findTemplateParameters();

            computeEffectiveName();

            List<FileObject> pf = null;

            for (CreateFromTemplateHandler h : Lookup.getDefault().lookupAll(CreateFromTemplateHandler.class)) {

                if (h.accept(desc)) {

                    pf = h.createFromTemplate(desc);

                    assert pf != null && !pf.isEmpty();

                    break;

                }

            }

            if (pf != null) {

                return pf;

            }

            // side effects from findTemplateParameters still in effect...

            return Collections.singletonList(defaultCreate());

        } finally {

            // bring back the parameters

            builder.getDescriptor().parameters = (Map<String, Object>)originalParams;

        }

    }

    private void computeEffectiveName() {

        String name = desc.getName();

        if (name == null) {

            // name is not set - try to check parameters, if some template attribute handler

            // did not supply a suggestion:

            Object o = desc.getParameters().get("name");

            if (o instanceof String) {

                name = (String)o;

            } else {

                name = FileUtil.findFreeFileName(

                           desc.getTarget(), desc.getTemplate().getName (), desc.getTemplate().getExt ()

                       );

            }

        }

        desc.proposedName = name;

    }

    /**

     * Populates default values for template parameters. Each template can have its specific parameters and their default values

     * are defined by {@link CreateFromTemplateAttributes} SPI registered in the Lookup. The 'param' provides user-defined values,

     * which always take precedence over the defaults.

     * <p/>

     * Certain values are always filled in, if not specified:

     * <ul>

     * <li>{@code user} the invoking user name

     * <li>{@code date} system date : String

     * <li>{@code time} system time : String

     * <li>{@code dateTime} java.util.Date representation of the current system time

     * </ul>

     * 

     * @param template

     * @param folder

     * @param name

     * @param param

     * @return completed parameters

     */

    public Map<String,Object> findTemplateParameters() {

        // IMPORTANT: all map is exposed through CreateDescriptor !

        HashMap<String,Object> all = new HashMap<String,Object>();

        all.putAll(desc.getParameters());

        originalParams = desc.parameters;

        desc.parameters = all;

        for (CreateFromTemplateAttributes provider : Lookup.getDefault().lookupAll(CreateFromTemplateAttributes.class)) {

            Map<String,? extends Object> map = provider.attributesFor(desc);

            if (map != null) {

                for (Map.Entry<String,? extends Object> e : map.entrySet()) {

                    // allow each CFTA override previous CFTAs, but not user-provided params

                    if (originalParams == null || !originalParams.containsKey(e.getKey())) {

                        all.put(e.getKey(), e.getValue());

                    }

                }

            }

        }

        String name = desc.getName();

        if (!all.containsKey("name") && name != null) { // NOI18N

            String n = name;

            if (Boolean.TRUE.equals(all.get(CreateFromTemplateHandler.FREE_FILE_EXTENSION))) {

                n = name.replaceFirst("[.].*", "");

            }

            all.put("name", n); // NOI18N

            //desc.name = name;

        }

        Date d = new Date();

        if (!all.containsKey("dateTime")) { // NOI18N

            all.put("dateTime", d); // NOI18N

        }

        String ext = desc.getTemplate().getExt();

        if (!all.containsKey("nameAndExt") && name != null) { // NOI18N

            if (ext != null && ext.length() > 0 && originalParams != null &&

                    (!Boolean.TRUE.equals(originalParams.get(CreateFromTemplateHandler.FREE_FILE_EXTENSION)) || name.indexOf('.') == -1)) {

                all.put("nameAndExt", name + '.' + ext); // NOI18N

            } else {

                all.put("nameAndExt", name); // NOI18N

            }

        }

        return all;

    }

    /**

     * Creates the file using the default algorithm - no handler is willing to participate

     * @return created file

     * @throws IOException 

     */

    private FileObject defaultCreate() throws IOException {

//        if (pf != null || defaultMode == TemplateUtils.Mode.FAIL) {

//            return pf;

//        }

        Map<String, ?> params = desc.getParameters();

        FileBuilder.Mode defaultMode = builder.defaultMode;

        Format frm = builder.format;

        if (defaultMode != FileBuilder.Mode.COPY && frm instanceof MapFormat) {

            MapFormat mf = (MapFormat)frm;

            Map m = mf.getMap();

            for (String s: params.keySet()) {

                if (m.containsKey(s)) {

                    continue;

                }

                m.put(s, params.get(s));

            }

        }

        FileObject f = desc.getTemplate();

        String ext = desc.getTemplate().getExt();

        FileObject fo = desc.getTarget().createData (desc.getProposedName(), ext);

        boolean preformatted = false;

        Charset encoding = FileEncodingQuery.getEncoding(f);

        boolean success = false;

        FileLock lock = fo.lock ();

        try (InputStream is= f.getInputStream ();

            Reader reader = new InputStreamReader(is,encoding);

            BufferedReader r = new BufferedReader (reader)) {

            Object attr = f.getAttribute(EA_PREFORMATTED);

            if (attr != null && attr instanceof Boolean) {

                preformatted = ((Boolean)attr);

            }

            encoding = FileEncodingQuery.getEncoding(fo);

            //Document doc = ScriptingCreateFromTemplateHandler.createDocument(f.getMIMEType());

            ScriptEngine en = ScriptingCreateFromTemplateHandler.indentEngine();

            // PENDING: originally, preformatted meant that only changed

            // lines were formatted. Now preformatted is not formatted at all

            StringWriter sw = new StringWriter();

            try (

                OutputStream os=fo.getOutputStream(lock);

                OutputStreamWriter w = new OutputStreamWriter(os, encoding);

                Writer iw = preformatted || en == null ? w : sw) {

                String line = null;

                String current;

                while ((current = r.readLine ()) != null) {

                    if (line != null) {

                        // newline between lines

                        iw.append(NEWLINE);

                    }

                    if (frm != null) {

                        line = frm.format (current);

                    } else {

                        line = current;

                    }

                    iw.append(line);

                }

                iw.append(NEWLINE);

                iw.flush();

                if (en != null) {

                    en.getContext().setAttribute("mimeType", f.getMIMEType(), ScriptContext.ENGINE_SCOPE);

                    en.getContext().setWriter(w);

                    en.eval(new StringReader(sw.toString()));

                }

            }

            // copy attributes

            // hack to overcome package-private modifier in setTemplate(fo, boolean)

            FileUtil.copyAttributes(f, fo);

            fo.setAttribute(PROP_TEMPLATE, null);

            success = true;

        } catch (IOException ex) {

            try {

                fo.delete(lock);

            } catch (IOException ex2) {

            }

            throw ex;

        } catch (ScriptException ex) {

            IOException io = ex.getCause() instanceof IOException ? (IOException)ex.getCause() : null;

            try {

                fo.delete(lock);

            } catch (IOException ex2) {

            }

            throw io == null ? new IOException(ex) : io;

        } finally {

            if (!success) {

                // try to delete the malformed file:

                fo.delete(lock);

            }

            lock.releaseLock();

        }

        return fo;

    }

}

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2014 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2014 Sun Microsystems, Inc.

 */

package org.netbeans.api.templates;

import java.io.IOException;

import java.text.FieldPosition;

import java.text.Format;

import java.text.ParsePosition;

import java.util.Date;

import java.util.HashMap;

import java.util.List;

import java.util.Locale;

import java.util.Map;

import org.netbeans.api.annotations.common.CheckForNull;

import org.netbeans.api.annotations.common.NonNull;

import org.netbeans.api.annotations.common.NullAllowed;

import org.openide.filesystems.FileObject;

import org.openide.util.MapFormat;

/**

 * Fluent interface for file creation. The Builder is first parametrized. After

 * everything is set up, call {@link #build} to materialize the template using

 * the supplied parameters/settings.

 * <p/>

 * 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 {@link #name}.

 * <p/>

 * The file build request will be forwarded to {@link CreateFromTemplateHandler}s; if none

 * {@link CreateFromTemplateHandler#accept}s the request, the default procedure takes place,

 * depending on the {@link #defaultMode} setting (default: {@link Mode#COPY}).

 * <p/>

 * There are several values predefined:<ul>

 * <li>name - the created filename without extension

 * <li>nameAndExt - the created filename including the extension

 * <li>date - date of creation, printed in the default date format

 * <li>dateTime - {@link Date} object representing the creation time

 * <li>time - time of creation, printed in the default time format

 * <li>user - the user id of the user creating the file

 * </ul>

 * 

 * @author sdedic

 */

public final class FileBuilder {

    /**

     * Determines the default procedure for copying the template in {@link #createFromTemplate}.

     */

    public static enum Mode {

        /**

         * The template will be formatted using formatter.

         */

        FORMAT, 

        /**

         * The template will be just copied.

         */

        COPY, 

        /**

         * The template will not be processed if no custom {@link CreateFromTemplateHandler} handles it.

         */

        FAIL

    }

    /**

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

     * @param template the template to use.

     * @param target the target folder; must already exist.

     */

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

        descriptor = new CreateDescriptor(template, target);

    }

    /**

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

     * @param l the locale

     * @return this FileBuilder instance.

     */

    public FileBuilder    useLocale(@NonNull Locale l) {

        descriptor.locale = l;

        return this;

    }

    /**

     * Sets the desired target file's name. 

     * 

     * @param n the name

     * @return this FileBuilder instance

     */

    public FileBuilder    name(String n) {

        descriptor.name = n;

        return this;

    }

    /**

     * Includes parameters for the template.

     * @param params the string-value pairs

     * @return this FileBuilder instance

     */

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

        if (descriptor.parameters != null) {

            descriptor.parameters.putAll(params);

        } else {

            descriptor.parameters = params == null ? null : new HashMap<>(params);

        }

        return this;

    }

    /**

     * Adds a parameter to the template.

     * @param n parameter name

     * @param v the value

     * @return this FileBuilder instance

     */

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

        if (descriptor.parameters == null) {

            descriptor.parameters = new HashMap<>();

        }

        descriptor.parameters.put(n, v);

        return this;

    }

    /**

     * Specifies the behaviour to be used when no {@link CreateFromTemplateHandler} accepts the template.

     * @param m the default processing mode

     * @return this FileBuilder instance

     * @see Mode for details

     */

    public FileBuilder    defaultMode(@NonNull Mode m) {

        this.defaultMode = m;

        return this;

    }

    /**

     * Uses the specified formatter for file creation. Also sets the default mode to

     * {@link Mode#FORMAT}. If the supplied Format instance <i>happens to be</i> a

     * {@link MapFormat}, the templating code will pass parameters produced by

     * {@link CreateFromTemplateAttributes} to the format when the target file

     * contents is generated.

     * 

     * @param def the format to use

     * @return  this FileBuilder instance

     * @see Mode for details on different modes

     */

    public FileBuilder    useFormat(@NonNull Format def) {

        this.format = def;

        return defaultMode(Mode.FORMAT);

    }

    /**

     * Creates the file(s) from template.

     * @return 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

     */

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

        return CreateFromTemplateImpl.build(this);

    }

    CreateDescriptor    getDescriptor() {

        return descriptor;

    }

    private final CreateDescriptor descriptor;

    @SuppressWarnings("PackageVisibleField")

    Mode    defaultMode;

    @SuppressWarnings("PackageVisibleField")

    Format  format;

    /**

     * Creates a new file based on the template. This convenience method is intended for easier

     * migration of clients using DataLoader templating API before {@link FileBuilder} introduction.

     * The method will collect parameters

     * tied to the template using registered {@link CreateFromTemplateAttributes} providers,

     * and will try to locate a willing {@link CreateFromTemplateHandler} that will create

     * the target file. If no such handler exists, and the {@code defaultCopy} parameter is true,

     * the file contents is just copied to the target location.

     * <p/>

     * If the {@code name} parameter is null, the function attempts to compute a suitable name

     * from the file.

     * <p/>

     * The default copy algorithm uses the supplied {@code format} to process tokens. A standard

     * format (using __TOKEN__) can be obtained by calling {@link #basicFormatter}.

     * <p/>

     * If the passed {@code name} is {@code null}, the implementation will pick a free name based on

     * the template's own name (see {@link FileUtil#findFreeFileName}).

     * @param f the template file

     * @param folder the target folder, must exist

     * @param name the desired name. If {@code null}, the implementation will choose the name.

     * @param attributes values to apply on the template. May be {@code null} = no values.

     * @return The created file, or {@code null} if no creation handler is located.

     * @throws IOException 

     */

    @SuppressWarnings("AssignmentToMethodParameter")

    @CheckForNull

    public static FileObject createFromTemplate(@NonNull FileObject f, @NonNull FileObject folder, 

            @NullAllowed String name, @NullAllowed Map<String, ?> attributes,

            Mode defaultMode) 

    throws IOException {

        Format frm = null;

        switch (defaultMode) {

            case FORMAT:

                MapFormat mf = new MapFormat(new HashMap());

                mf.setExactMatch(false);

                mf.setLeftBrace("__");

                mf.setRightBrace("__");

                frm = mf;

                break;

            case COPY:

                frm = new Format() {

                    @Override

                    public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos) {

                        toAppendTo.append(obj);

                        return toAppendTo;

                    }

                    @Override

                    public Object parseObject(String source, ParsePosition pos) {

                        throw new UnsupportedOperationException("Not supported yet."); //To change body of generated methods, choose Tools | Templates.

                    }

                };                    

                break;

        }

        FileBuilder fb = new FileBuilder(f, folder).

                            name(name).

                            withParameters(attributes).

                            useFormat(frm).

                            defaultMode(defaultMode);

        List<FileObject> fos = fb.build();

        if (fos == null || fos.isEmpty()) {

            return null;

        } else {

            return fos.iterator().next();

        }

    }

}

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2011 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common Development and

 * Distribution License("CDDL") (collectively, the "License"). You may not use

 * this file except in compliance with the License. You can obtain a copy of

 * the License at http://www.netbeans.org/cddl-gplv2.html or

 * nbbuild/licenses/CDDL-GPL-2-CP. See the License for the specific language

 * governing permissions and limitations under the License. When distributing

 * the software, include this License Header Notice in each file and include

 * the License file at nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this

 * particular file as subject to the "Classpath" exception as provided by

 * Oracle in the GPL Version 2 section of the License file that accompanied

 * this code. If applicable, add the following below the License Header, with

 * the fields enclosed by brackets [] replaced by your own identifying

 * information: "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL or

 * only the GPL Version 2, indicate your decision by adding "[Contributor]

 * elects to include this software in this distribution under the [CDDL or GPL

 * Version 2] license." If you do not indicate a single choice of license, a

 * recipient has the option to distribute your version of this file under

 * either the CDDL, the GPL Version 2 or to extend the choice of license to its

 * licensees as provided above. However, if you add GPL Version 2 code and

 * therefore, elected the GPL Version 2 license, then the option applies only

 * if the new code is made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2011 Sun Microsystems, Inc.

 */

package org.netbeans.api.templates;

import java.lang.annotation.ElementType;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.lang.annotation.Target;

import javax.script.ScriptEngineFactory;

/**

 * Registers a template the user can select.

 * May be placed on a class (with a default constructor) or static method (with no arguments)

 * to register an {@link InstantiatingIterator} for a custom template;

 * or on a package to register a plain-file template with no custom behavior.

 * @since 7.29

 * @see TemplateWizard

 * @see TemplateRegistrations

 * @see <a href="@org-netbeans-modules-projectuiapi@/org/netbeans/spi/project/ui/templates/support/package-summary.html"><code>org.netbeans.spi.project.ui.templates.support</code></a>

 */

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.PACKAGE})

@Retention(RetentionPolicy.SOURCE)

public @interface TemplateRegistration {

    /**

     * Subfolder in which to place the template, such as {@code Other} or {@code Project/Standard}.

     */

    String folder();

    /**

     * Optional position within {@link #folder}.

     */

    int position() default Integer.MAX_VALUE;

    /**

     * Special file basename to use rather than inferring one from the declaring element,

     * when {@link #content} is empty.

     * Useful for pure templates referenced from {@code PrivilegedTemplates}.

     */

    String id() default "";

    /**

     * File contents, as resources relative to the package of this declaration.

     * A nonempty list is mandatory for a template registered on a package.

     * For a template with a custom iterator, the content may be omitted, though it may still be specified.

     * <p>Normally only a single file is specified, but for a multifile data object, list the primary entry first.

     * <p>The file basenames (incl. extension) of the actual template files (as in {@link TemplateWizard#getTemplate})

     * will be taken from the basename of the content resources, though a {@code .template} suffix

     * may be appended to prevent template resources in a source project from being misinterpreted.

     * For a "pure" custom iterator with no specified content, the template basename

     * defaults to the FQN of the class or method defining it but with {@code -} for {@code .} characters,

     * e.g. {@code pkg-Class-method}, but may be overridden with {@link #id}.

     * <p>Example usage for a simple, single-file template (with or without custom iterator):

     * <pre>content="resources/empty.php"</pre>

     * <p>For a form template:

     * <pre>content={"Login.java.template", "Login.form.template"}</pre>

     */

    String[] content() default {};

    /**

     * Localized label for the template.

     * Mandatory unless {@link #content} is specified, in which case it would be defaulted by the data node.

     * May use the usual {@code #key} syntax.

     */

    String displayName() default "";

    /**

     * Icon to use for the template.

     * Should be an absolute resource path (no initial slash).

     * Mandatory unless {@link #content} is specified, in which case it would be defaulted by the data node.

     */

    String iconBase() default "";

    /**

     * Optional but recommended relative resource path to an HTML description of the template.

     * @see TemplateWizard#getDescription

     */

    String description() default "";

    /**

     * Optional name of a script engine to use when processing file content, such as {@code freemarker}.

     * @see ScriptEngineFactory#getNames

     */

    String scriptEngine() default "";

    /**

     * Optional list of categories interpreted by the project system.

     */

    String[] category() default {};

    /**

     * Set to false if the template can be instantiated without a project.

     * @since 7.46

     */

    boolean requireProject() default true;

    /**

     * Default (pre-filled) target name for the template, without extension. May

     * use the usual {@code #key} syntax for localization or branding.

     *

     * @since 7.56

     */

    String targetName() default "";

}

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2011 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common Development and

 * Distribution License("CDDL") (collectively, the "License"). You may not use

 * this file except in compliance with the License. You can obtain a copy of

 * the License at http://www.netbeans.org/cddl-gplv2.html or

 * nbbuild/licenses/CDDL-GPL-2-CP. See the License for the specific language

 * governing permissions and limitations under the License. When distributing

 * the software, include this License Header Notice in each file and include

 * the License file at nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this

 * particular file as subject to the "Classpath" exception as provided by

 * Oracle in the GPL Version 2 section of the License file that accompanied

 * this code. If applicable, add the following below the License Header, with

 * the fields enclosed by brackets [] replaced by your own identifying

 * information: "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL or

 * only the GPL Version 2, indicate your decision by adding "[Contributor]

 * elects to include this software in this distribution under the [CDDL or GPL

 * Version 2] license." If you do not indicate a single choice of license, a

 * recipient has the option to distribute your version of this file under

 * either the CDDL, the GPL Version 2 or to extend the choice of license to its

 * licensees as provided above. However, if you add GPL Version 2 code and

 * therefore, elected the GPL Version 2 license, then the option applies only

 * if the new code is made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2011 Sun Microsystems, Inc.

 */

package org.netbeans.api.templates;

import java.lang.annotation.ElementType;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.lang.annotation.Target;

/**

 * May be used to register multiple plain-file {@link TemplateRegistration}s.

 * Use on a package for simple templates, or on an iterator for multiple variants of a template

 * with different {@link TemplateRegistration#content}.

 * @since 7.29

 */

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.PACKAGE})

@Retention(RetentionPolicy.SOURCE)

public @interface TemplateRegistrations {

    TemplateRegistration[] value();

}

OpenIDE-Module-Display-Category=Infrastructure

OpenIDE-Module-Long-Description=\

    Provides API to create files based on templates. Supports scripting in templates \

    and allows to plug in code that handles file creation, or supplies project or \

    environment data for template creation.

OpenIDE-Module-Name=File Templates

OpenIDE-Module-Short-Description=Supports file creation based on templates

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 1997-2010 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * Contributor(s):

 *

 * The Original Software is NetBeans. The Initial Developer of the Original

 * Software is Sun Microsystems, Inc.

 *

 * Portions Copyrighted 2007 Sun Microsystems, Inc.

 */

package org.netbeans.modules.templates;

import java.io.IOException;

import java.io.InputStreamReader;

import java.io.OutputStreamWriter;

import java.io.PrintWriter;

import java.io.Reader;

import java.io.StringReader;

import java.io.StringWriter;

import java.io.Writer;

import java.nio.charset.Charset;

import java.util.Collections;

import java.util.List;

import java.util.Map;

import javax.script.Bindings;

import javax.script.ScriptContext;

import javax.script.ScriptEngine;

import javax.script.ScriptEngineManager;

import javax.script.ScriptException;

import org.netbeans.api.queries.FileEncodingQuery;

import org.netbeans.api.templates.CreateDescriptor;

import org.netbeans.api.templates.CreateFromTemplateHandler;

import org.openide.filesystems.FileObject;

import org.openide.filesystems.FileUtil;

import org.openide.util.Lookup;

import org.openide.util.lookup.ServiceProvider;

/** Processes templates that have associated attribute

* with name of the scripting engine.

*

* @author  Jaroslav Tulach

*/

@ServiceProvider(service=CreateFromTemplateHandler.class)

public class ScriptingCreateFromTemplateHandler extends CreateFromTemplateHandler {

    public static final String SCRIPT_ENGINE_ATTR = "javax.script.ScriptEngine";

    private static ScriptEngineManager manager;

    private static final String ENCODING_PROPERTY_NAME = "encoding"; //NOI18N

    @Override

    public boolean accept(CreateDescriptor desc) {

        return engine(desc.getTemplate()) != null;

    }

    @Override

    public List<FileObject> createFromTemplate(CreateDescriptor desc) throws IOException {

        return Collections.singletonList(createFromTemplate(

            desc.getTemplate(),

            desc.getTarget(),

            desc.getName(),

            desc.getParameters()

        ));

    }

    private FileObject createFromTemplate(FileObject template, FileObject f,

                                            String name,

                                            Map<String, Object> values) throws IOException {

        boolean noExt = Boolean.TRUE.equals(values.get(FREE_FILE_EXTENSION)) && name.indexOf('.') != -1;

        String extWithDot;

        if (noExt) {

            extWithDot = null;

        } else {

            extWithDot = '.' + template.getExt();

            if (name.endsWith(extWithDot)) { // Test whether the extension happens to be there already

                // And remove it if yes, it will be appended to the unique name.

                name = name.substring(0, name.length() - extWithDot.length());

            }

        }

        String nameUniq = FileUtil.findFreeFileName(f, name, noExt ? null : template.getExt());

        FileObject output = FileUtil.createData(f, noExt ? nameUniq : nameUniq + extWithDot);

        Charset targetEnc = FileEncodingQuery.getEncoding(output);

        Charset sourceEnc = FileEncodingQuery.getEncoding(template);

        ScriptEngine eng = engine(template);

        Bindings bind = eng.getContext().getBindings(ScriptContext.ENGINE_SCOPE);

        bind.putAll(values);

        if(!values.containsKey(ENCODING_PROPERTY_NAME)) {

            bind.put(ENCODING_PROPERTY_NAME, targetEnc.name());

        }

        //Document doc = createDocument(template.getMIMEType());

        try (Writer w = new OutputStreamWriter(output.getOutputStream(), targetEnc);

             Reader is = new InputStreamReader(template.getInputStream(), sourceEnc);

            /*IndentWriter w2 = new IndentWriter(doc, 0, w, false) */) {

            StringWriter sw = new StringWriter();

            ScriptEngine eng2 = indentEngine();

            eng.getContext().setWriter(new PrintWriter(eng2 != null ? sw : w));

            //eng.getContext().setBindings(bind, ScriptContext.ENGINE_SCOPE);

            eng.getContext().setAttribute(FileObject.class.getName(), template, ScriptContext.ENGINE_SCOPE);

            eng.getContext().setAttribute(ScriptEngine.FILENAME, template.getNameExt(), ScriptContext.ENGINE_SCOPE);

            eng.eval(is);

            if (eng2 != null) {

                eng2.getContext().setAttribute("mimeType", template.getMIMEType(), ScriptContext.ENGINE_SCOPE);

                eng2.getContext().setWriter(w);

                eng2.eval(new StringReader(sw.toString()));

            }

        }catch (ScriptException ex) {

            IOException io = new IOException(ex.getMessage(), ex);

            throw io;

        }

        return output;

    }

    public static ScriptEngine indentEngine() {

        return getEngine(ID_INDENT_ENGINE);

    }

    private static final String ID_INDENT_ENGINE = "org.netbeans.api.templates.IndentEngine"; // NOI18N

    public static ScriptEngine getEngine(String engName) {

        synchronized (ScriptingCreateFromTemplateHandler.class) {

            if (manager == null) {

                ClassLoader loader = Lookup.getDefault().lookup(ClassLoader.class);

                manager = new ScriptEngineManager(loader != null ? loader : Thread.currentThread().getContextClassLoader());

            }

        }

        return manager.getEngineByName(engName);

    }

    private static ScriptEngine engine(FileObject fo) {

        Object obj = fo.getAttribute(SCRIPT_ENGINE_ATTR); // NOI18N

        if (obj instanceof ScriptEngine) {

            return (ScriptEngine)obj;

        }

        if (obj instanceof String) {

            return getEngine((String)obj);

        }

        return null;

    }

    /*

    public static Document createDocument(String mimeType) {

        Document doc;

        try {

            doc = LineDocumentUtils.createDocument(mimeType);

        } catch (IllegalArgumentException ex) {

            // mainly for tests

            doc = new PlainDocument();

            doc.putProperty("mimeType", mimeType);

        }

        return doc;

    }

    */

}

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2011 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common Development and

 * Distribution License("CDDL") (collectively, the "License"). You may not use

 * this file except in compliance with the License. You can obtain a copy of

 * the License at http://www.netbeans.org/cddl-gplv2.html or

 * nbbuild/licenses/CDDL-GPL-2-CP. See the License for the specific language

 * governing permissions and limitations under the License. When distributing

 * the software, include this License Header Notice in each file and include

 * the License file at nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this

 * particular file as subject to the "Classpath" exception as provided by

 * Oracle in the GPL Version 2 section of the License file that accompanied

 * this code. If applicable, add the following below the License Header, with

 * the fields enclosed by brackets [] replaced by your own identifying

 * information: "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL or

 * only the GPL Version 2, indicate your decision by adding "[Contributor]

 * elects to include this software in this distribution under the [CDDL or GPL

 * Version 2] license." If you do not indicate a single choice of license, a

 * recipient has the option to distribute your version of this file under

 * either the CDDL, the GPL Version 2 or to extend the choice of license to its

 * licensees as provided above. However, if you add GPL Version 2 code and

 * therefore, elected the GPL Version 2 license, then the option applies only

 * if the new code is made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2011 Sun Microsystems, Inc.

 */

package org.netbeans.modules.templates;

import java.net.URI;

import java.net.URISyntaxException;

import java.util.Arrays;