| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| --> |
| <!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="dstrupl@netbeans.org" |
| > |
| |
| &api-questions; |
| |
| |
| |
| <!-- |
| <question id="arch-what"> |
| What is this project good for? |
| <hint> |
| Please provide here a few lines describing the project, |
| what problem it should solve, provide links to documentation, |
| specifications, etc. |
| </hint> |
| </question> |
| --> |
| <answer id="arch-what"> |
| In summary, the <api name="LoadersAPI" group="java" type="export" category="official" url="@TOP@org/openide/loaders/doc-files/api.html" /> |
| is responsible for scanning files in a directory on disk, |
| weeding out irrelevant files of no interest to the IDE, |
| and grouping the rest into logical chunks, or just determining |
| what type of data each represents. It does this scanning by asking each registered |
| data loader whether or not the given file(s) should be handled. The first |
| loader to recognize a file takes ownership of it, and creates a matching data object to represent it to the rest of the IDE. |
| </answer> |
| |
| <answer id="arch-usecases" > |
| A lot of usecases is described <a href="@TOP@/org/openide/loaders/doc-files/api.html" >in the javadoc</a>. Here |
| is the list of some faqs: |
| |
| <usecase id="script" name="Using Scripting and Templating Languages" > |
| <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/openide/loaders/DataObject.html#createFromTemplate-org.openide.loaders.DataFolder-java.lang.String-java.util.Map-"> |
| 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, however since |
| version 6.1 there are new interfaces |
| <api name="org.openide.loaders.CreateFromTemplateHandler" category="deprecated" group="lookup" type="export" |
| url="@TOP@/org/openide/loaders/CreateFromTemplateHandler.html"> |
| 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> and |
| <api name="org.openide.loaders.CreateFromTemplateAttributesProvider" category="deprecated" group="lookup" type="export" |
| url="@TOP@/org/openide/loaders/CreateFromTemplateAttributesProvider.html"> |
| 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 without writing new |
| <a href="@TOP@/org/openide/loaders/DataLoader.html">DataLoader</a> and co. |
| </p> |
| <p> |
| The support was moved to a new module; please see <a href="@org-netbeans-api-templates@/architecture-summary.html">api.templates</a> |
| module for more information. |
| </p> |
| </usecase> |
| <usecase id="add-action-to-folder" name="How to add action to folder's popup menu?" > |
| <api name="Loaders-folder-any-Actions" category="stable" group="layer" type="export" > |
| The actions that the default folder loader shows in its popup menu are read from |
| a layer folder <code>Loaders/folder/any/Actions</code> |
| so if any module wishes |
| to extend, hide or reorder some of them it can just register its actions there.</api> |
| As code like this does: |
| <pre> |
| <folder name="Loaders" > |
| <folder name="folder" > |
| <folder name="any" > |
| <folder name="Actions" > |
| <file name="org-mymodule-MyAction.instance" > |
| <attr name="instanceCreate" stringvalue="org.mymodule.MyAction" /> |
| </file> |
| </folder> |
| </folder> |
| </folder> |
| </folder> |
| </pre> |
| As described in general <a href="@org-openide-actions@/org/openide/actions/doc-files/api.html#adv-install"> |
| actions registration tutorial</a>. |
| <p/> |
| This functionality is available since version 5.0 of the loaders module. Please use |
| <code>OpenIDE-Module-Module-Dependencies: org.openide.loaders > 5.0</code> in your |
| module dependencies. |
| <p> |
| In version 5.8 all the standard loaders were changed to read actions |
| from layer: |
| </p> |
| <ul> |
| <li><api name="Loaders-text-xml-Actions" category="stable" group="layer" type="export" > |
| The actions that the standard XML loader shows in its popup menu are read from |
| a layer folder <code>Loaders/text/xml/Actions</code></api></li> |
| |
| <li><api name="Loaders-content-unknown-Actions" category="stable" group="layer" type="export" > |
| The actions that the loader for unrecognized files shows in its popup menu are read from |
| a layer folder <code>Loaders/content/unknown/Actions</code></api></li> |
| |
| <li><api name="Loaders-application-x-nbsettings-Actions" category="stable" group="layer" type="export" > |
| The actions that the loader for instance and settings files shows in its popup menu are read from |
| a layer folder <code>Loaders/application/x-nbsettings/Actions</code></api></li> |
| </ul> |
| </usecase> |
| |
| <usecase id="let-others-to-add-actions-to-loader" name="How to allow others to enhance actions of your loader?" > |
| If you want other modules to enhance or modify actions that are visible on |
| <code>DataObject</code>s produced by your <code>DataLoader</code> and you |
| are either using <code>DataNode</code> or its subclass, you can just override |
| <code>protected String actionsContext()</code> method to return non-null |
| location of context in layers from where to read the actions. |
| <p/> |
| The usual value should match <code>Loaders/mime/type/Actions</code> scheme, |
| for example java is using <code>Loaders/text/x-java/Actions</code>, but |
| the name can be arbitrary. |
| <p/> |
| This functionality is available since version 5.0 of the loaders module. Please use |
| <code>OpenIDE-Module-Module-Dependencies: org.openide.loaders > 5.0</code> in your |
| module dependencies. |
| </usecase> |
| </answer> |
| |
| <!-- Question: compat-i18n |
| |
| <question id="compat-i18n"> |
| Is your module correctly internationalized? |
| </question> |
| --> |
| <answer id="compat-i18n"> |
| Yes. |
| </answer> |
| |
| |
| |
| <!-- Question: compat-standards |
| |
| <question id="compat-standards"> |
| Does the module implements or defines any standards? Is the |
| implementation exact or it deviates somehow? |
| </question> |
| --> |
| <answer id="compat-standards"> |
| No. |
| </answer> |
| |
| |
| |
| <!-- Question: compat-version |
| |
| <question id="compat-version"> |
| Does your module properly coexists with earlier and future |
| versions? Can you correctly read settings? Will future |
| versions be able to read settings? |
| |
| <hint> |
| Very helpful for reading settings is to store version number |
| there, so future versions can decide whether how to read/convert |
| the settings and older versions can ignore the new ones. |
| </hint> |
| </question> |
| --> |
| <answer id="compat-version"> |
| No answer |
| </answer> |
| |
| |
| |
| <!-- Question: dep-jre |
| |
| <question id="dep-jre"> |
| Which version of JRE you need (1.2, 1.3, 1.4, etc.)? |
| </question> |
| --> |
| <answer id="dep-jre"> |
| JRE 1.3. |
| </answer> |
| |
| |
| |
| <!-- Question: dep-jrejdk |
| |
| <question id="dep-jrejdk"> |
| Do you require JDK or is JRE enough? |
| </question> |
| --> |
| <answer id="dep-jrejdk"> |
| JRE is enough. |
| </answer> |
| |
| |
| |
| <!-- Question: dep-nb |
| |
| <question id="dep-nb"> |
| What other NetBeans projects this one depends on? |
| </question> |
| --> |
| <answer id="dep-nb"> |
| It depends on |
| <api name="FilesystemsAPI" type="import" url="@org-openide-filesystems@/org/openide/filesystems/doc-files/api.html" category="official" group="java" />, |
| <api name="LookupAPI" type="import" url="@org-openide-util@/org/openide/util/doc-files/api.html#lookup" category="official" group="java" />, |
| <api name="UtilitiesAPI" type="import" url="@org-openide-util@/org/openide/util/doc-files/api.html" category="official" group="java" />. |
| </answer> |
| |
| |
| |
| <!-- Question: dep-non-nb |
| |
| <question id="dep-non-nb"> |
| What other non-NetBeans projects this one depends on? |
| |
| <hint> |
| Some non-NetBeans projects are packaged as NetBeans modules |
| and |
| it is prefered to use this approach when more modules may |
| depend on such third-party library. |
| </hint> |
| </question> |
| --> |
| <answer id="dep-non-nb"> |
| It does not depend on any external library. |
| </answer> |
| |
| |
| |
| <!-- Question: dep-platform |
| |
| <question id="dep-platform"> |
| On which platforms your module run? Any? Does it run in the same |
| way? |
| </question> |
| --> |
| <answer id="dep-platform"> |
| It runs on any platform. |
| </answer> |
| |
| |
| |
| <!-- Question: deploy-jar |
| |
| <question id="deploy-jar"> |
| Do you deploy just module JAR file(s) or some other files? |
| </question> |
| --> |
| <answer id="deploy-jar"> |
| Data Systems are integral part of openide.jar. |
| </answer> |
| |
| |
| |
| <!-- Question: deploy-nbm |
| |
| <question id="deploy-nbm"> |
| Can you deploy NBM via AutoUpdate center? |
| </question> |
| --> |
| <answer id="deploy-nbm"> |
| Yes. openide.jar can be deployed via AutoUpdate. |
| </answer> |
| |
| |
| |
| <!-- Question: deploy-packages |
| |
| <question id="deploy-packages"> |
| Are packages of your module made inaccessible by not declaring them |
| public? |
| |
| <hint> |
| NetBeans module system allows restriction of access rights to |
| public classes of your module from other modules. This prevents |
| unwanted dependencies of others on your code and should be used |
| public packages |
| </a>). |
| </hint> |
| </question> |
| --> |
| <answer id="deploy-packages"> |
| No. |
| </answer> |
| |
| |
| |
| <!-- Question: deploy-shared |
| |
| <question id="deploy-shared"> |
| Do you need to be installed in shared location or only in user directory? |
| </question> |
| --> |
| <answer id="deploy-shared"> |
| openide.jar needs to be in the system directory. |
| </answer> |
| |
| |
| |
| <!-- Question: exec-classloader |
| |
| <question id="exec-classloader"> |
| Does your code uses own classloader? |
| </question> |
| --> |
| <answer id="exec-classloader"> |
| No. |
| </answer> |
| |
| |
| |
| <!-- Question: exec-component |
| |
| <question id="exec-component"> |
| Is execution of your code influenced by (string) property |
| of any of your components? |
| </question> |
| --> |
| <answer id="exec-component"> |
| The data system stores some of its vital information in file attributes. Those |
| attributes are accessible via calls to |
| org.openide.filesystems.FileObject.getAttribute(name) |
| org.openide.filesystems.FileObject.setAttribute(name, value) |
| They can also be stored in the module layer. Please see filesystems |
| for more information about this. |
| |
| <api type="export" group="property" name="NetBeansAttrAssignedLoader" category="stable" > |
| Extended attribute for holding the class of the loader that should |
| be used to recognize a file object before the normal processing takes |
| place. |
| </api> |
| |
| <api type="export" group="property" name="NetBeansAttrAssignedLoaderModule" category="private" > |
| Extended attribute which may be used in addition to EA_ASSIGNED_LOADER |
| which indicates the code name base of the module that installed that preferred |
| loader. If the indicated module is not installed, ignore the loader request. |
| See #13816. |
| </api> |
| |
| <api type="export" group="property" name="template" category="stable" > |
| If set to Boolean.TRUE the file is recognized as template and |
| its instantiation is allowed. |
| </api> |
| |
| <!-- TemplateWizard: --> |
| |
| <api type="export" group="property" name="isRemoteAndSlow" category="friend"> |
| If the file attribute <code>isRemoteAndSlow</code> is <code>true</code> on a folder, |
| the New File wizard will avoid asking for its children. |
| </api> |
| |
| |
| <api type="export" group="property" name="templateWizardURL" category="stable" > |
| Attribute that defines a template wizard description page (type <code>URL</code> to HTML). |
| </api> |
| |
| <api type="export" group="property" name="templateWizardIterator" category="stable" > |
| Attribute that defines a custom template wizard iterator (type <code>TemplateWizard.Iterator</code>). |
| </api> |
| |
| |
| <!-- DataShadow: --> |
| |
| <api type="export" group="property" name="originalFile" category="stable" > |
| Path to the target file in its filesystem (type <code>String</code>). |
| </api> |
| |
| <api type="export" group="property" name="originalFileSystem" category="stable" > |
| System name of filesystem of target file (type <code>String</code>; default is same as that of shadow). |
| </api> |
| |
| <api type="export" group="property" name="UseOwnName" category="private" > |
| if true, the DataShadow name is used instead of original's name, |
| affects DataShadows of filesystem roots only |
| </api> |
| |
| <api type="export" group="property" name="simple" category="stable" > |
| templates and folders under <code>Templates/</code> |
| folder can be annotated with <attr name="simple" boolvalue="false"< |
| if they are supposed to be hidden in <em>Template Manager</em>. |
| If a folder is annotated with this attribute, it is also hidden |
| in standard <em>New File wizard</em>. |
| </api> |
| |
| <!-- FolderOrder: --> |
| <api type="export" group="property" name="PartialOrders" category="stable" > |
| Read the list of intended partial orders from disk. |
| Each element is a string of the form <samp>a/b</samp> for <samp>a</samp>, <samp>b</samp> filenames |
| with extension, where <samp>a</samp> should come before <samp>b</samp>. |
| The value of the attribute must be of type <code>Boolean</code>; ignored unless <code>true</code>. |
| </api> |
| |
| <!-- DataFolder: --> |
| <api type="export" group="property" name="OpenIDE-Folder-SortMode" category="private" > |
| Extended attribute for order of children. The values |
| are "F", "N", "C", "0" (type <code>String</code>). |
| </api> |
| |
| <api type="export" group="property" name="OpenIDE-Folder-Order" category="private" > |
| Extended attribute for order of children - stores list |
| of file names separated by '/' (type <code>String</code>). |
| </api> |
| |
| <!-- FolderChildren --> |
| |
| <api type="export" group="systemproperty" name="org.openide.loaders.FolderChildren.delayedCreation" category="devel"> |
| <p> |
| Since 7.25 the <code>DataFolder.getNodeDelegate()</code> tries to prevent |
| creation of <a href="@TOP@/org/openide/loaders/DataObject.html">DataObject</a> |
| in AWT dispatch thread. Rather it creates dummy node with name |
| derived from the name of the file and simplified content of lookup: |
| </p> |
| <ul> |
| <li><a href="@org-openide-filesystems@/org/openide/filesystems/FileObject.html">FileObject</a> |
| - the file that the node represents</li> |
| <li><a href="@org-openide-nodes@/org/openide/nodes/Node.html">Node</a> |
| - the node itself, but without any important properties</li> |
| <li><a href="@TOP@/org/openide/loaders/DataObject.html">DataObject</a> |
| - created on the fly, very <b>inefficient</b>, if requested from |
| AWT dispatch thread, it prints a warning. Consider using |
| just <a href="@org-openide-filesystems@/org/openide/filesystems/FileObject.html">FileObject</a>.</li> |
| </ul> |
| <p> |
| The creation of real node is scheduled to background and as soon as |
| the |
| <a href="@TOP@/org/openide/loaders/DataObject.html">DataObject</a> |
| and its |
| <a href="@org-openide-nodes@/org/openide/nodes/Node.html">Node</a> are |
| ready, the initial dummy node is replaced by the real one. |
| </p> |
| <p> |
| This whole system is slightly incompatible and may complicate creation |
| of filtered views over the node hierarchy (one needs to be ready to |
| really dynamics changes). That is why it is possible to disable |
| the new <q>delayed</q> system by starting the system with |
| <code>-Dorg.openide.loaders.FolderChildren.delayedCreation=false</code>. |
| Use this property as a temporary fix for your problems, but consider |
| fixing your code to support the <q>delayed mode</q> in the future. |
| </p> |
| </api> |
| |
| <!-- ConnectionSupport: --> |
| <api type="export" group="property" name="EA-OpenIDE-Connection" category="private" > |
| Extended attribute to store (ArrayList of Type and Node.Handle). |
| Used by Java synchronization feature at least; generally, <code>ConnectionCookie</code>. |
| </api> |
| |
| <api type="export" group="property" name="DataFolder.Index.reorderable" category="friend"> |
| If set to <code>Boolean.TRUE</code> on a folder not in the system filesystem, make its node reorderable. |
| </api> |
| <api type="import" group="property" name="expectedTime" category="friend" > |
| When the DataObject is moved to new location, we |
| we need to adjust the time to the new file object. |
| <a href="@org-openide-text@/org/openide/text/CloneableEditorSupport.html">CloneableEditorSupport</a> |
| exports special "expectedTime" property for this purpose. Tested |
| in <code>DataEditorSupportTest.testChangeFileWhileOpen</code>. |
| </api> |
| </answer> |
| |
| |
| |
| <!-- Question: exec-property |
| |
| <question id="exec-property"> |
| Is execution of your code influenced by any environment of |
| system (<code>System.getProperty</code>) property? |
| </question> |
| --> |
| <answer id="exec-property"> |
| <!-- XMLDataObject: --> |
| <api type="import" group="property" name="org.xml.sax.driver" category="private" > |
| This is a standard way to find a class of a SAX2 driver. See |
| <a href="http://www.saxproject.org/"> SAX2 documentation </a> |
| </api> |
| |
| <api type="import" group="property" name="netbeans.profile.memory" category="private" > |
| Boolean.TRUE means to dettach from shared impl of parser, it is static!? |
| </api> |
| |
| <api type="export" group="systemproperty" name="org.openide.loaders.FolderList.refresh.interval" category="private" > |
| The value of type integer determines the number of milliseconds |
| between successive refreshes of contents of a folder. Can be used to tweak |
| performance of folder refresh. Defaults to 10. |
| </api> |
| |
| <api group="systemproperty" category="friend" name="netbeans.dataobject.insecure.operation" type="export" > |
| If set to <b>true</b>, the <code>DataObject.copy, move, createFromTemplate</code> |
| are executed in insecure way. That means that other threads can access the |
| products of such operation before it finishes. This is a friend contract |
| with projects, that need to do such strange things. Will be removed when they |
| fix it. |
| </api> |
| |
| <api group="javax.swing.UIManager" category="devel" name="Nb.Explorer.Folder.icon" type="export" > |
| Icon or Image for closed folder. |
| </api> |
| |
| <api group="javax.swing.UIManager" category="devel" name="Nb.Explorer.Folder.openedIcon" type="export" > |
| Icon or Image for opened folder. |
| </api> |
| |
| <api group="javax.swing.UIManager" category="devel" name="Tree.openedIcon" type="export" > |
| Fallback Icon or Image for opened folder. |
| </api> |
| |
| <api group="javax.swing.UIManager" category="devel" name="Tree.closedIcon" type="export" > |
| Fallback Icon or Image for folder. |
| </api> |
| |
| <api group="property" category="stable" name="wizard.anything" type="export" > |
| When <a href="@TOP@/org/openide/loaders/TemplateWizard.html">TemplateWizard</a> invokes |
| <a href="@TOP@/org/openide/loaders/DataObject.html">DataObject</a>.createFromTemplate, |
| it passes as argument all its <a href="@org-openide-dialogs@/org/openide/WizardDescriptor.html#getProperties--">properties</a> |
| to it with prefix <code>wizard.</code>. That way they are available to |
| underlaying <a href="@TOP@/architecture-summary.html#script">scripting and templating |
| engines</a>. |
| </api> |
| </answer> |
| |
| |
| |
| <!-- Question: format-clipboard |
| |
| <question id="format-clipboard"> |
| Which protocols your code reads/inserts when communicating with |
| clipboard? |
| </question> |
| --> |
| <answer id="format-clipboard"> |
| We use following MIME type: |
| application/x-java-openide-dataobjectdnd;class=org.openide.loaders.DataObject;mask={0} |
| </answer> |
| |
| |
| |
| <!-- Question: format-dnd |
| |
| <question id="format-dnd"> |
| Which protocols your code understands during drag-n-drop? |
| </question> |
| --> |
| <answer id="format-dnd"> |
| We use following MIME type: |
| application/x-java-openide-dataobjectdnd;class=org.openide.loaders.DataObject;mask={0} |
| </answer> |
| |
| |
| |
| <!-- Question: format-types |
| |
| <question id="format-types"> |
| Which file formats your code reads or writes on disk? |
| </question> |
| --> |
| <answer id="format-types"> |
| Any file format. |
| </answer> |
| |
| |
| |
| <!-- Question: lookup-lookup |
| |
| <question id="lookup-lookup"> |
| Does your module used <code>org.openide.util.Lookup</code> |
| to find any components to communicate to? Which ones? |
| </question> |
| --> |
| <answer id="lookup-lookup"> |
| <ul> |
| <li>DataLoaderPool.class </li> |
| <li>ActionManager.class</li> |
| <li>(in XMLDataObject) Node.Cookie.class</li> |
| <li>RepositoryNodeFactory.class</li> |
| <li>ModuleInfo.class</li> |
| <li>ClassLoader.class</li> |
| </ul> |
| <p> |
| If there is no <code>DataLoaderPool</code> available in default |
| lookup, the fallback is to use a simple loader pool that contains |
| just the fixed <q>system</q> loaders, and any |
| <code>DataLoader</code>s that can be found in default lookup. |
| </p> |
| DataFolder.FolderNode.setName() looks for one instance of org.openide.loaders.FolderRenameHandler. |
| </answer> |
| |
| |
| |
| <!-- Question: lookup-register |
| |
| <question id="lookup-register"> |
| Do you register anything into the lookup for other to find? Who are |
| the others? |
| </question> |
| --> |
| <answer id="lookup-register"> |
| Registration of |
| <ul> |
| <li>DataLoaderPool.class</li> |
| <li>Environment.Provider.class</li> |
| <li>RepositoryNodeFactory.class</li> |
| </ul> |
| is done in core in META-INF/services. |
| </answer> |
| |
| |
| |
| <!-- Question: lookup-remove |
| |
| <question id="lookup-remove"> |
| Are removing entries of other modules from the lookup? Why? |
| </question> |
| --> |
| <answer id="lookup-remove"> |
| No. |
| </answer> |
| |
| |
| |
| <!-- Question: perf-exit |
| |
| <question id="perf-exit"> |
| Does your module executes anything on exit? |
| </question> |
| --> |
| <answer id="perf-exit"> |
| No. |
| </answer> |
| |
| |
| |
| <!-- Question: perf-huge_dialogs |
| |
| <question id="perf-huge_dialogs"> |
| Does your module contain any dialogs or wizards with huge |
| amount of GUI controls like combo boxes, lists, trees, text |
| areas? |
| </question> |
| --> |
| <answer id="perf-huge_dialogs"> |
| This module contains infrastructure for creating "New" functionality |
| wizards. |
| </answer> |
| |
| |
| |
| <!-- Question: perf-limit |
| |
| <question id="perf-limit"> |
| Are there any limits in number/size of elements your code |
| can handle? |
| </question> |
| --> |
| <answer id="perf-limit"> |
| No. |
| </answer> |
| |
| |
| |
| <!-- Question: perf-mem |
| |
| <question id="perf-mem"> |
| What is the amount of memory your component occupies? Estimate |
| with a relaction to the number of windows, etc. |
| </question> |
| --> |
| <answer id="perf-mem"> |
| Unknown. |
| </answer> |
| |
| |
| |
| <!-- Question: perf-menus |
| |
| <question id="perf-menus"> |
| Does your module use dynamically changing context menus or |
| context sensitive actions with complicated logic for enable/disable? |
| </question> |
| --> |
| <answer id="perf-menus"> |
| No. |
| </answer> |
| |
| <!-- Question: perf-progress |
| |
| <question id="perf-progress"> |
| Does your module executes some long running task? |
| <hint>Typically they are tasks like connecting over |
| network, computing huge amount of data, compilation. |
| Such communication should be done asynchronously (for example |
| using <code>RequestProcessor</code>), definitively it should |
| not block AWT thread. |
| </hint> |
| </question> |
| --> |
| <answer id="perf-progress"> |
| The module uses its own RequestProcessors to handle long running |
| tasks. |
| </answer> |
| |
| |
| |
| <!-- Question: perf-scale |
| |
| <question id="perf-scale"> |
| Which external criteria influence the performance of your |
| program (size of file in editor, number of files in menu, |
| in source directory, etc.) and how well your code scales? |
| Please include some estimates. |
| </question> |
| --> |
| <answer id="perf-scale"> |
| Performance of some operations |
| is lineary proportional to number of files in a given |
| folder times number of registered data loaders in |
| the pool. |
| |
| </answer> |
| |
| |
| |
| <!-- Question: perf-startup |
| |
| <question id="perf-startup"> |
| Does your module executes anything on startup? |
| </question> |
| --> |
| <answer id="perf-startup"> |
| Yes. The list of loaders is read from the disk to memory. |
| </answer> |
| |
| |
| |
| <!-- Question: perf-wakeup |
| |
| <question id="perf-wakeup"> |
| Is any piece of your code waking up periodically? |
| </question> |
| --> |
| <answer id="perf-wakeup"> |
| No. |
| </answer> |
| |
| |
| |
| <!-- Question: resources-file |
| |
| <question id="resources-file"> |
| Does your module use <code>java.io.File</code> directly? |
| |
| <hint> |
| NetBeans provide a logical wrapper over plain files called |
| <code>org.openide.filesystems.FileObject</code> that |
| provides uniform access to such resources and is the prefered |
| way that should be used. But of course there can be situations when |
| this is not suitable. |
| </hint> |
| </question> |
| --> |
| <answer id="resources-file"> |
| No. |
| </answer> |
| |
| |
| |
| <!-- Question: resources-layer |
| |
| <question id="resources-layer"> |
| Does your module provide own layer? Does it create some files or |
| folders on it? What it is trying to communicate by that and with which |
| component? |
| |
| <hint> |
| NetBeans allows automatic and declarative installation of resources |
| by module layers. Module register files into appropriate places |
| and other components use that information to perform their task |
| (build menu, toolbar, window layout, list of templates, set of |
| options, etc.). |
| </hint> |
| </question> |
| --> |
| <answer id="resources-layer"> |
| <p> |
| <api name="Loaders-mime-type-Factories" group="layer" type="export" category="stable" |
| url="@TOP@/org/openide/loaders/doc-files/api.html#register" |
| > |
| Loaders are registered in the layer in folder <code>Loaders/mime/type/Factories</code>. |
| </api> |
| </p> |
| <p> |
| Yes, module creates the folders in layer <samp>org/netbeans/core/ui/resources/layer.xml</samp> |
| in <samp>core-ui.jar</samp>. The folders are instrumental to store information |
| about used templates. |
| <b>Provided folders: </b> |
| </p> |
| <ul> |
| <li> |
| <api name="PrivilegedTemplates" group="layer" type="export" category="devel"> |
| A folder Privileged offers to other module possibility add own templates. |
| </api><p></p> |
| </li> |
| <li> |
| <api name="RecentTemplates" group="layer" type="export" category="private"> |
| A folder Recent stores a set of recently used templates, it's not open to other module. |
| </api><p></p> |
| </li> |
| <li> |
| <api name="Menu" group="layer" type="export" category="stable"><p> |
| The main menu of the application is composed by reading <code>Menu/</code> |
| folder in the layer. A sub folder is treated as a sub menu. |
| Instances of individual files (usually <code>.instance</code> |
| or <code>.shadow</code>) may then represent <a href="@JDK@/javax/swing/Action.html">Action</a> |
| or <a href="@JDK@/javax/swing/JMenuItem.html">JMenuItem</a> |
| or <a href="@JDK@/javax/swing/JSeparator.html">JSeparator</a>. |
| </p> |
| <p> |
| Since version 7.44 one can attach <code>property-prefix</code> attribute |
| to every folder. Then all the file attributes are scanned and if some |
| of them start with the specified prefix they are placed a |
| <a href="@JDK@/javax/swing/JComponent.html#putClientProperty-java.lang.Object-java.lang.Object-"> |
| client |
| properties</a> on the <a href="@JDK@/javax/swing/JMenu.html">JMenu</a> |
| instance (after stripping the prefix off). |
| </p> |
| </api><p></p> |
| </li> |
| </ul> |
| <p> |
| None of them is forced to found. |
| </p> |
| </answer> |
| |
| <!-- Question: resources-mask |
| |
| <question id="resources-mask"> |
| Does your module read any resource provided by another one in |
| module layer? Why? |
| </question> |
| --> |
| <answer id="resources-mask"> |
| No. |
| </answer> |
| |
| |
| |
| <!-- Question: resources-read |
| |
| <question id="resources-read"> |
| Does your module read any resources from layers? For what purpose? |
| </question> |
| --> |
| <answer id="resources-read"> |
| NewTemplateAction reads a list of templates from folders Privileged and Recent. |
| This list is exposed in a popup menu. |
| </answer> |
| |
| |
| |
| |
| |
| <!-- |
| <question id="arch-overall" when="init"> |
| Describe the overall architecture. |
| <hint> |
| What will be API for |
| <a href="http://openide.netbeans.org/tutorial/api-design.html#design.apiandspi" shape="rect"> |
| clients and what support API</a>? |
| What parts will be pluggable? |
| How will plug-ins be registered? Please use <code><api type="export"/></code> |
| to describe your general APIs and specify their |
| <a href="http://openide.netbeans.org/tutorial/api-design.html#category-private" shape="rect"> |
| stability categories</a>. |
| If possible please provide simple diagrams. |
| </hint> |
| </question> |
| --> |
| <answer id="arch-overall"> |
| <p> |
| This module provides API (read <a href="@TOP@org/openide/loaders/doc-files/api.html">more</a>) |
| that works on top of <a href="@org-openide-filesystems@/overview-summary.html">file objects</a> |
| and gives each file a logical behaviour - icon, name, operations, etc. |
| </p> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="arch-quality" when="init"> |
| How will the <a href="http://www.netbeans.org/community/guidelines/q-evangelism.html" shape="rect">quality</a> |
| of your code be tested and |
| how are future regressions going to be prevented? |
| <hint> |
| What kind of testing do |
| you want to use? How much functionality, in which areas, |
| should be covered by the tests? How you find out that your |
| project was successful? |
| </hint> |
| </question> |
| --> |
| <answer id="arch-quality"> |
| <p> |
| XXX no answer for arch-quality |
| </p> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="arch-time" when="init"> |
| What are the time estimates of the work? |
| <hint> |
| Please express your estimates of how long the design, implementation, |
| stabilization are likely to last. How many people will be needed to |
| implement this and what is the expected milestone by which the work should be |
| ready? |
| </hint> |
| </question> |
| --> |
| <answer id="arch-time"> |
| <p> |
| XXX no answer for arch-time |
| </p> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="arch-where" when="impl"> |
| Where one can find sources for your module? |
| <hint> |
| Please provide link to the CVS web client at |
| http://www.netbeans.org/download/source_browse.html |
| or just use tag defaultanswer generate='here' |
| </hint> |
| </question> |
| --> |
| <answer id="arch-where"> |
| <defaultanswer generate='here' /> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="compat-deprecation" when="init"> |
| How the introduction of your project influences functionality |
| provided by previous version of the product? |
| <hint> |
| If you are planning to deprecate/remove/change any existing APIs, |
| list them here accompanied with the reason explaining why you |
| are doing so. |
| </hint> |
| </question> |
| --> |
| <answer id="compat-deprecation"> |
| <p> |
| XXX no answer for compat-deprecation |
| </p> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="deploy-dependencies" when="final"> |
| What do other modules need to do to declare a dependency on this one, |
| in addition to or instead of the normal module dependency declaration |
| (e.g. tokens to require)? |
| <hint> |
| Provide a sample of the actual lines you would add to a module manifest |
| to declare a dependency, for example OpenIDE-Module-Requires: some.token. |
| If other modules should not depend on this module, or should just use a |
| simple regular module dependency, you can just answer "nothing". If you |
| intentionally expose a semistable API to clients using implementation |
| dependencies, you should mention that here (but there is no need to give |
| an example of usage). |
| </hint> |
| </question> |
| --> |
| <answer id="deploy-dependencies"> |
| <p> |
| XXX no answer for deploy-dependencies |
| </p> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="exec-ant-tasks" when="impl"> |
| Do you define or register any ant tasks that other can use? |
| |
| <hint> |
| If you provide an ant task that users can use, you need to be very |
| careful about its syntax and behaviour, as it most likely forms an |
| API for end users and as there is a lot of end users, their reaction |
| when such API gets broken can be pretty strong. |
| </hint> |
| </question> |
| --> |
| <answer id="exec-ant-tasks"> |
| <p> |
| XXX no answer for exec-ant-tasks |
| </p> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="exec-introspection" when="impl"> |
| Does your module use any kind of runtime type information (<code>instanceof</code>, |
| work with <code>java.lang.Class</code>, etc.)? |
| <hint> |
| Check for cases when you have an object of type A and you also |
| expect it to (possibly) be of type B and do some special action. That |
| should be documented. The same applies on operations in meta-level |
| (Class.isInstance(...), Class.isAssignableFrom(...), etc.). |
| </hint> |
| </question> |
| --> |
| <answer id="exec-introspection"> |
| <p> |
| No. |
| </p> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="exec-privateaccess" when="final"> |
| Are you aware of any other parts of the system calling some of |
| your methods by reflection? |
| <hint> |
| If so, describe the "contract" as an API. Likely private or friend one, but |
| still API and consider rewrite of it. |
| </hint> |
| </question> |
| --> |
| <answer id="exec-privateaccess"> |
| <p> |
| XXX no answer for exec-privateaccess |
| </p> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="exec-process" when="impl"> |
| Do you execute an external process from your module? How do you ensure |
| that the result is the same on different platforms? Do you parse output? |
| Do you depend on result code? |
| <hint> |
| If you feed an input, parse the output please declare that as an API. |
| </hint> |
| </question> |
| --> |
| <answer id="exec-process"> |
| <p> |
| XXX no answer for exec-process |
| </p> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="exec-reflection" when="impl"> |
| Does your code use Java Reflection to execute other code? |
| <hint> |
| This usually indicates a missing or insufficient API in the other |
| part of the system. If the other side is not aware of your dependency |
| this contract can be easily broken. |
| </hint> |
| </question> |
| --> |
| <answer id="exec-reflection"> |
| <p> |
| XXX no answer for exec-reflection |
| </p> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="exec-threading" when="init"> |
| What threading models, if any, does your module adhere to? How the |
| project behaves with respect to threading? |
| <hint> |
| Is your API threadsafe? Can it be accessed from any threads or |
| just from some dedicated ones? Any special relation to AWT and |
| its Event Dispatch thread? Also |
| if your module calls foreign APIs which have a specific threading model, |
| indicate how you comply with the requirements for multithreaded access |
| (synchronization, mutexes, etc.) applicable to those APIs. |
| If your module defines any APIs, or has complex internal structures |
| that might be used from multiple threads, declare how you protect |
| data against concurrent access, race conditions, deadlocks, etc., |
| and whether such rules are enforced by runtime warnings, errors, assertions, etc. |
| Examples: a class might be non-thread-safe (like Java Collections); might |
| be fully thread-safe (internal locking); might require access through a mutex |
| (and may or may not automatically acquire that mutex on behalf of a client method); |
| might be able to run only in the event queue; etc. |
| Also describe when any events are fired: synchronously, asynchronously, etc. |
| Ideas: <a href="http://core.netbeans.org/proposals/threading/index.html#recommendations" shape="rect">Threading Recommendations</a> (in progress) |
| </hint> |
| </question> |
| --> |
| <answer id="exec-threading"> |
| <p> |
| XXX no answer for exec-threading |
| </p> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="perf-spi" when="init"> |
| How the performance of the plugged in code will be enforced? |
| <hint> |
| If you allow foreign code to be plugged into your own module, how |
| do you enforce that it will behave correctly and quickly and will not |
| negatively influence the performance of your own module? |
| </hint> |
| </question> |
| --> |
| <answer id="perf-spi"> |
| <p> |
| XXX no answer for perf-spi |
| </p> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="resources-preferences" when="final"> |
| Does your module uses preferences via Preferences API? Does your module use NbPreferences or |
| or regular JDK Preferences ? Does it read, write or both ? |
| Does it share preferences with other modules ? If so, then why ? |
| <hint> |
| You may use |
| <api type="export" group="preferences" |
| name="preference node name" category="private"> |
| description of individual keys, where it is used, what it |
| influences, whether the module reads/write it, etc. |
| </api> |
| Due to XML ID restrictions, rather than /org/netbeans/modules/foo give the "name" as org.netbeans.modules.foo. |
| Note that if you use NbPreferences this name will then be the same as the code name base of the module. |
| </hint> |
| </question> |
| --> |
| <answer id="resources-preferences"> |
| <p> |
| <api category="devel" group="preferences" name="org.openide.actions.FileSystemRefreshAction.manual" type="export"> |
| If <code>NbPreferences.root().node("org/openide/actions/FileSystemRefreshAction").getBoolean("manual", false)</code> |
| returns true, then <a href="@TOP@/org/openide/actions/FileSystemRefreshAction.html">FileSystemRefreshAction</a> |
| is displayed in popup menu of folders. |
| </api> |
| </p> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="security-grant" when="final"> |
| Does your code grant additional rights to some other code? |
| <hint>Avoid using a class loader that adds extra |
| permissions to loaded code unless really necessary. |
| Also note that your API implementation |
| can also expose unneeded permissions to enemy code by |
| calling AccessController.doPrivileged().</hint> |
| </question> |
| --> |
| <answer id="security-grant"> |
| <p> |
| XXX no answer for security-grant |
| </p> |
| </answer> |
| |
| |
| |
| <!-- |
| <question id="security-policy" when="final"> |
| Does your functionality require modifications to the standard policy file? |
| <hint>Your code might pass control to third-party code not |
| coming from trusted domains. This could be code downloaded over the |
| network or code coming from libraries that are not bundled |
| with NetBeans. Which permissions need to be granted to which domains?</hint> |
| </question> |
| --> |
| <answer id="security-policy"> |
| <p> |
| XXX no answer for security-policy |
| </p> |
| </answer> |
| |
| </api-answers> |
