View All Attachments for Bug 70280

This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.

Attachment #27782
Initial Draft from Dec 12, 2005	text/html	2005-12-13 10:06:04 UTC	70.34 KB	no flags	Details

<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Actions - NetBeans Architecture Questions</title>
<link rel="stylesheet" type="text/css" href="prose.css">
</head>
<body>
<p class="overviewlink">
<a href="overview-summary.html">Overview</a>
</p>
<h1>NetBeans Architecture Answers for Actions module</h1>
<ul>
<li>
<b>Author:</b> jtulach@netbeans.org</li>
<li>
<b>Answers as of:</b> 13.12.2005</li>
<li>
<b>Answers for questions version:</b> 1.26</li>
<li>
<b>Latest available version of questions:</b> 1.26</li>
</ul>
<hr>
<h2>Interfaces table</h2>
<a name="group-java">
<h5>Group of java interfaces</h5>
</a>
<table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%">
<tr>
<td>
<table border="0" cellpadding="3" cellspacing="1" width="100%">
<tr class="tablersh">
<td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td>
</tr>
<tr class="tabler">
<td>ProgressAPI</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-stable">Stable</a></td><td><a name="java-ProgressAPI"><a href="http://www.netbeans.org/download/dev/javadoc/org-netbeans-api-progress/overview-summary.html">
                            .http://www.netbeans.org/download/dev/javadoc/overview-summary.html</a>
<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>UtilitiesAPI</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-official">Official</a></td><td><a name="java-UtilitiesAPI"><a href="http://www.netbeans.org/download/dev/javadoc/org-openide-util/overview-summary.html">http://www.netbeans.org/download/dev/javadoc/org-openide-util/overview-summary.html</a>
<p></p>
</a></td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<a name="group-property">
<h5>Group of property interfaces</h5>
</a>
<table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%">
<tr>
<td>
<table border="0" cellpadding="3" cellspacing="1" width="100%">
<tr class="tablersh">
<td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td>
</tr>
<tr class="tabler">
<td>ActionMapKeys</td><td>Exported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-stable">Stable</a></td><td><a name="property-ActionMapKeys">
<p></p>
                certain keys has been published by the platform and modules can use
                them to register their own implementation in action maps of their 
                components:
                <ul>
                    
<li>
<code>"cloneWindow"</code> - an action to be executed when a top component is to be cloned</li>
                    
<li>
<code>"closeWindow"</code> - an action when a view is about to be closed</li>
                    
<li>
<code>DefaultEditorKit.copyAction</code> - copy action handler</li>
                    
<li>
<code>DefaultEditorKit.cutAction</code> - cut action handler</li>
                    
<li>
<code>"delete"</code> - delete action handler</li>
                    
<li>
<code>DefaultEditorKit.pasteAction</code> - paste action handler</li>
                    
<li>
<code>"jumpNext"</code> - when a next element shall be selected</li>
                    
<li>
<code>"jumpPrev"</code> - when a previous element shall be selected</li>
                
</ul>
            
<p></p>
</a></td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<!--
                Sun Public License Notice

The contents of this file are subject to the Sun Public License
Version 1.0 (the "License"). You may not use this file except in
compliance with the License. A copy of the License is available at
http://www.sun.com/

The Original Code is NetBeans. The Initial Developer of the Original
Code is Sun Microsystems, Inc. Portions Copyright 1997-2005 Sun
Microsystems, Inc. All Rights Reserved.
-->
<api-answers author="jtulach@netbeans.org" module="Actions" question-version="1.26">

  
<!--
                Sun Public License Notice

The contents of this file are subject to the Sun Public License
Version 1.0 (the "License"). You may not use this file except in
compliance with the License. A copy of the License is available at
http://www.sun.com/

The Original Code is NetBeans. The Initial Developer of the Original
Code is Sun Microsystems, Inc. Portions Copyright 1997-2004 Sun
Microsystems, Inc. All Rights Reserved.
-->

<!--
    Author     : Jaroslav Tulach
    Description: Questions that should be answered in order to make better API

    No PUBLIC or SYSTEM IDs defined currently.
-->


<!--
                        *** ATTENTION EDITORS ***
Please increment the 'version' field of <api-questions> whenever you make a
semantic change: adding a new question or significantly changing the meaning of
an old one. Changing this field ensures that arch pages answering the old version
print a warning during Javadoc generation. If you only change hints or make small
edits in the text of a question, you need not change the version number.

Also rerun openide/www/tutorial/build.xml#question when you are done and commit
openide/www/tutorial/questions.html.
-->

<api-questions version="1.26" xml:base="file:/doma/jarda/netbeans-src/nbbuild/antsrc/org/netbeans/nbbuild/Arch-api-questions.xml">
    
<hr>
<h2>General Information</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-arch-what">Question (arch-what)</a>:</b><em>
            What is this project good for?
            
        </em></font>
<p></p>
<b>Answer:</b>
    
<p>
    This module provides support for creation of actions, supports and
    takes care of their presentation in global menus, toolbars and popup 
    menu. By using methods and other APIs from this module one shall be
    able to easily create instances of <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/Action.html" shape="rect">javax.swing.Action</a>
    which are ready to use in the NetBeans platform.
    </p>

<p></p>
<font color="gray"><b><a name="answer-arch-overall">Question (arch-overall)</a>:</b><em>
            Describe the overall architecture. 
            
        </em></font>
<p></p>
<b>Answer:</b>
    
<p>
    The architecture of this module builds on existing NetBeans Platform
    abstractions that seem useful. This lowers the amount of changes in comparition
    from NetBeans 5.0 and concentrates them into relatively small, isolated
    area. The basic building block is 
    <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-util/org/openide/util/Utilities.html#actionGlobalContext" shape="rect">
        Utilities.actionGlobalContext()
    </a> and 
    <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-util/org/openide/util/ContextAwareAction.html" shape="rect">
        ContextAwareAction
    </a> interface. These were introduced to solve focus problems when 
    creating pop up menus on window managers with other then click-to-focus
    behaviours and seem to work quite well.
    </p>
    
    
<p>
    One of the most important goals is to remove the need to work with
    historic <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-util/org/openide/util/actions/SystemAction.html" shape="rect">
        SystemAction
    </a> and subclasses. Beyond the fact the they are instances of
    <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-util/org/openide/util/SharedClassObject.html" shape="rect">
        SharedClassObject
    </a> and such they have limited, complex and not very useful lifecycle
    managment, they also rely on old and currently already obsolete concepts
    like <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-nodes/org/openide/nodes/Node.Cookie.html" shape="rect">Node.Cookie</a>.
    By using this module one does not need to care about the 
    <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-util/org/openide/util/actions/SystemAction.html" shape="rect">
        SystemAction
    </a> at all. <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-nodes/org/openide/nodes/Node.Cookie.html" shape="rect">Node.Cookie</a>
    is required no more as well.
    </p>
    
    
<h5>Out Of Scope</h5>
    
    
<p>
        Part of overall description is also list of things that are not addressed
        by the effort. So it is wise to state that the actions module does not 
        addresses following issues:
    </p>
    
    
<ul>
        
<li>No changes to registration - e.g. stick with what we have in layers.xml now</li>
    
</ul>
 
<p></p>
<font color="gray"><b><a name="answer-arch-usecases">Question (arch-usecases)</a>:</b><em>
            
        
            Describe the main <a href="http://openide.netbeans.org/tutorial/api-design.html#usecase" shape="rect">
            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?
        </em></font>
<p></p>
<b>Answer:</b>
    
<h4>Always Enabled Action</h4>
    
<p>
        One can create a context-less, always enabled action. Of course,
        one can use <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/AbstractAction.html" shape="rect">javax.swing.AbstractAction</a>
        to do that, however the support provided by this module allows one
        important addition - the action can be registered and displayed
        without loading any of the classes into memory. This is helpful
        for actions like <q>Open File</q>, <q>Open Project</q>, most of actions
        in <q>Window</q> submenu that opens singleton components and etc.
    </p>
    
    
<p>
        To register such action in a layer file use following syntax:
    </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.api.actions.Factory.delegate" /&gt;
    &lt;attr name="delegate" newvalue="your.module.Listener" &gt;
  &lt;/file&gt;
</pre>
    
<p>
        And write a class <code>your.module.Listener</code> that extends
        <code>javax.swing.ActionListener</code> and implements its 
        <code>actionPeformed</code> method. 
    </p>
    
    
<p>
        Such action is going to be always enabled and when invoked the registered
        listener is going to be instantiated and its method called. The localized
        name and icon of the action is going to be taken from the localized
        name and icon for the file using the standard branding mechanism for
        layers - e.g. <code>SystemFileSystem.localizingBundle</code> attribute, etc.
    </p>
    
    
    
    
<h4>Callback Action</h4>
    
<p>
       One can define a placeholder action - e.g. an action that has the 
       name, icon, shortcut, but does not have the actual implementation.
       Such implementation is then going to be discovered in runtime. 
       It is provided by the actual selected element (usually 
       <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.html" shape="rect">TopComponent</a>).
       Also the enabled/disabled state is governed by the selected element's
       advices.
    </p>
    
    
<p>
        There are two steps one needs to do to declare such action. First of
        all one needs to provide a key and register such action in a layer:
    </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.api.actions.Factory.callback" /&gt;
    &lt;attr name="key" stringvalue="your.module.Key" &gt;
  &lt;/file&gt;
</pre>
    
<p>
        The localization and icon is taken from the regular layer attributes.
        The value of the <q>key</q> then becomes the API that others can
        use to provide implementation of the action. So as a step two, one
        writes its own implementation of plain <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/Action.html" shape="rect">javax.swing.Action</a>
        and registers it into <q>the selected</q> 
        <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/ActionMap.html" shape="rect">ActionMap</a> - the 
        selected action map usually is 
        <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.html" shape="rect">TopComponent.getActionMap()</a>
        of the component one is writing the action for.
    </p>
    
    
<p>
        The <em>callback action</em> is then going to listen on the changes
        in selected elements and update it state according state of the action
        one wants to delegate to.
        <!-- btw. we could also delegate the name of the action! -->
    </p>
    
    
    
    
    
<h4>Support for Long Running Actions</h4>
    
<p>
        All actions are by default executed on AWT event thread. Also their
        enablement state is guaranteed to be computed on AWT thread as well.
        
    </p>    
    
<p>
        If an enablement state should take longer to compute, then it is 
        adviced to keep the action always enabled and if it is invoked 
        in an inapropriate situation then just do nothing.
    </p>
    
    
<p>
        If an execution of the action's performer it taking long time, then
        it is adviced to move the execution to background. User shall be
        notified about running background tasks by the use of the
        <a href="#java-ProgressAPI">ProgressAPI</a>.
    </p>
    
    
<p>
        To support testing and UI scripting a contract to invoke background
        actions synchronously shall be followed. If the <code>actionPerformed</code>
        method is called with <a href="http://java.sun.com/j2se/1.4.2/docs/api/java.awt.event.ActionEvent" shape="rect">
            ActionEvent(somone, id, "waitFinished")
        </a> command <q>waitFinished</q> then the actionPerformed method
        should return after whole initialization is over.
    </p>
    
    
<p>
        There is a support to make writing the above described contracts
        simpler. A factory method that takes an interface with three methods:
        one is called on AWT thread and returns a <code>ProgressHandle</code>,
        seconds is called outside of the thread and gets handle as an argument.
        Third method is again called on AWT thread and gets handle as well
        as returned value from the background method. The action created
        by this factory method honors the <q>waitFinished</q> contract.
    </p>
    
    
    
<h4>Context Aware Actions</h4>
    
<p>
        To support situation where one module does have a piece of data and
        wants other module to create an unlimited range of actions that 
        works on such data, NetBeans provide a powerful mechanism of context
        aware actions.
    </p>
    
    
<p>
        A module who wishes to expose a piece of data creates an interface
        in its API to encapsulate them and makes sure the interface get's exposed 
        in <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-util/org/openide/util/Utilities.html#actionGlobalContext" shape="rect">
        Utilities.actionGlobalContext()
        </a>. This can be done by putting the interface into 
        <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.html#getLookup()" shape="rect">lookup</a>
        of module's top components or 
        <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-nodes/org/openide/nodes/Node.html#getLookup()" shape="rect">lookup of its Nodes</a>.
    </p>
    
    
<p>
        The other modules then just use the <code>context</code> factory method
        with provided <code>Class&lt;DataType&gt;</code> of the API interface that encapsulates
        the data and provide subclass of <code>ContextActionPerformer&lt;DataType&gt;</code> 
        that provides implementation of 
        <code>actionPerformed(ActionEvent ev, DataType[] arr)</code>
        handling the execution of the action on given instances of DataType.
    </p>
    
    
<p>
        By using just the <code>ContextActionPerformer</code> one creates action
        that is always enabled if given <code>DataType</code> is present in the
        active context, that however may not be enough for all situations.
        For example project actions needs to extract the project from a
        file/data object and then decide. For them there is a way to also supply
        <code>ContextActionController&lt;DataType&gt;</code> that has method 
        <code>enabled(DataType[] types)</code> to compute the enabled state
        programmatically and control both the enablement and well as execution.
    </p>
 
    
<p>
        Context aware actions can be registered in a layer of module to prevent 
        the actual <code>ContextActionPerformer</code> to be instantiated until
        really needed:
    </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.api.actions.Factory.context" /&gt;
    &lt;attr name="type" stringvalue="your.module.DataType" &gt;
    &lt;attr name="actionPerformer" newvalue="your.module.ContextActionPerformerImpl" &gt;
  &lt;/file&gt;
</pre>
    
<p>
        As usually, display name and icon are taken by the standard attributes
        provided by SystemFileSystem.
    </p>
    
    
    
    
<h4>Adjusting Display Name to Context</h4>
    
<p>
        In some situations the display name of the action in menu or popup menu
        should change according the actual selection. This is supported for 
        those actions where it makes sence - the callback and context actions.
    </p>    
    
    
<p>
        When creating a callback action and can specify that the name shall
        be taken from the actual delegate. As a result either default name is
        used when there is noone to delegate to, or the name of the delegate is
        shown in menu and popup menu.
    </p>
    
    
<p>
        If one wishes to influence the display name of an action, one needs to
        write additional interface <code>ContextActionName</code> that's only
        method takes an array of <code>DataType</code> and returns string to
        be used for display name.
    </p>
    
    

    
<h4>Marking Default Action In Bold</h4>
        <!-- #9679 -->
        
<p>
            This is really old issue (#9679) and it is still open as it 
            seemed unsolvable till now. However recently it has been found
            that there is a way for the action to found out if it is the
            default action or not, if it uses the <code>Node.getPreferredAction()</code>
            method. If the context the actions works in contains just one
            node and someone is building a popup menu for it, then the one
            action returned from <code>Node.getPreferredAction()</code> can
            draw itself in bold. So this can work for 
            <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-nodes/org/openide/util/actions/NodeAction.html" shape="rect">NodeAction</a>
            and
            <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-nodes/org/openide/util/actions/CookieAction.html" shape="rect">CookieAction</a>
            for the other we need some kind of <q>node awarence</q>.
        </p>
        
        
<p>
            It seems reasonable to keep the actions framework as far from
            <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-nodes/overview-summary.html" shape="rect">nodes</a> as
            possible. That is why there is a <q>query</q> interface with one 
            method <code>Action findDefaultAction(Lookup context)</code> 
            define in the new action API and implemented in Node API and also
            anywhere else where such implementation is desirable. This interface
            is then use by default presenters of the actions to draw the one
            selected in bold.
        </p>
    
    
    
    
<h4>Handling Multi Selection</h4>
        
<p>
            Multiselection support is important for context actions. The other
            types do not need it. Always enabled are indeed always enabled and
            the callback actions just should not delegate to more than one
            delegate, that would unnecessary complicate things.
        </p>
        
        
<p>
            The easy and hopefully useful default behaviour for context actions
            shall be <q>some of them</q> mode: E.g. regarding of how many elements
            is selected, if at least one of them provides the desired context data,
            then the action is enabled, and if invoked, it will get access to
            all data that provided the context. To implement this one needs 
            just the notion of <code>DataType</code>, one does not need to care
            about the properties of the selection provider at all.
        </p>
        
        
<p>
            Anything else however gets more complicated. For example to support
            <q>just one</q> mode - where the action is enabled if one element
            is selected and provides the data - checking for present of one
            data interface is not enough. Doing that could lead to selection
            of multiple elements where just one of them would provide the correct
            data type in its context. So it is clear that the action framework
            needs to be somehow aware of the concept of <q>selected element</q>.
        </p>
        
        
<p>
            Shall the selected element be 
            <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-nodes/org/openide/nodes/Node.html" shape="rect">Node</a>?
            Well that is not good idea, as until now we managed to keep the
            actions API without a reference to Node and including such rich
            API like <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-nodes/overview-summary.html" shape="rect">nodes</a>
            would needlessly complicate the learning curve. Moreover not 
            all views are Node based - the CVS <q>before commit</q> table is
            likely implemented without node backend.
        </p>
        
        
<p>
            This seems to lead to a need for a new API between the actions and
            the views using the actions. Somehow they need to inform each other
            about the multiselection situation. The possible ways to do it
            include:
        </p>
        
        
<ul>
            
<li>query like pattern - it would process the current context and
                returned information about the number of selected elements.
                Would be implemented in Nodes to work correctly with nodes.
            </li>
            
<li>special <q>element</q> interface - would identify one selected
                element, <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-nodes/org/openide/nodes/Node.html" shape="rect">Node</a>
                node would be retrofitted to implement it.
            </li>
            
<li>use of <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-util/org/openide/util/Lookup.Provider.html" shape="rect">Lookup.Provider</a>
                as the element interface - not used that way until now, but 
                very likely would identify the element. No retrofitting would
                have to be done for 
                <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-nodes/org/openide/nodes/Node.html" shape="rect">Node</a>
                as it already implements that interface.
            </li>
            
<li>
                Lookup based contract - could use the differences between
                <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-util/org/openide/util/Lookup.Result.html#allItems" shape="rect">Result.allItems</a>
                and 
                <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-util/org/openide/util/Lookup.Result.html#allInstances" shape="rect">Result.allInstances</a>
                to notify the multiselection. The number of returned items
                would reflect the number of selected elements, those that
                do not provide the data type would return null. Similar pattern
                is already used to communitate null vs. Node[0] from 
                <code>TopComponent.getActivatedNodes()</code>.
            </li>
        
</ul>
        
        
<p>
            Regardless of what solution is finally selected, there is a clear
            need for an API between the actions framework and the views which
            needs to be addressed.
        </p>
        
    
    
    
<h4>Actions Acting On Last Suitable Context</h4>
        
<p>
            Sometimes it is reasonable to let the action to work on previous
            selection even if current selection does not have such actions. For
            example one may want the <q>Compile One File</q> action to work
            on last selected file even if we are for example in output window
            evaluating the errors printed by the compiler. And vice versa, 
            the <q>jump to next error</q> action provided by output should 
            work even if one is already in editor.
        </p>
        
        
<p>
            To create such context and callback actions one needs to specify,
            during their creation that they <q>survive focus change</q>. Then
            the action will remain associated with the last context that is 
            sufficent to trigger it:
        </p>
        
        
<ul>
            
<li>the callback action will always delegate to the delegate found in
            the last <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/ActionMap.html" shape="rect">ActionMap</a>
            that provided action for its key.
            </li>
            
            
<li>
            the context action will keep its state associated with data
            from previous context if the new one does not provide any 
            instance of the data interface.
            </li>
        
</ul>
        
        
<p>
            One can specify that newly created action shall survive focus change
            in layer as well. Just add attribute <q>surviveFocusChange</q>
            to specification of callback and context actions:
        </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.api.actions.Factory.context" /&gt;
    &lt;attr name="surviveFocusChange" boolvalue="true" &gt;
  &lt;/file&gt;
</pre>
    
    
    
<h4>Support same shortcut for different actions in different contexts</h4>
        <!-- #21184  -->
        
<p>
            There are multiple levels of such support. If the modules that 
            provide the different actions somehow
            know about each other, they can agree on a key, define a global
            callback action based on that key and then, in different contexts
            (e.g. <a href="http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/ActionMap.html" shape="rect">ActionMap</a>s)
            each module can register different action. 
            
            <a href="#property-ActionMapKeys">ActionMapKeys</a>
            - 
                certain keys has been published by the platform and modules can use
                them to register their own implementation in action maps of their 
                components:
                <ul>
                    
<li>
<code>"cloneWindow"</code> - an action to be executed when a top component is to be cloned</li>
                    
<li>
<code>"closeWindow"</code> - an action when a view is about to be closed</li>
                    
<li>
<code>DefaultEditorKit.copyAction</code> - copy action handler</li>
                    
<li>
<code>DefaultEditorKit.cutAction</code> - cut action handler</li>
                    
<li>
<code>"delete"</code> - delete action handler</li>
                    
<li>
<code>DefaultEditorKit.pasteAction</code> - paste action handler</li>
                    
<li>
<code>"jumpNext"</code> - when a next element shall be selected</li>
                    
<li>
<code>"jumpPrev"</code> - when a previous element shall be selected</li>
                
</ul>
            
            
            
<br>
            
            This style of <q>sharing</q> however requires that the modules
            know each other and also that the set of actions that shares the
            same key is defined at compile time.
        </p>
        
        
<p>
            There is another level of configurability - completely different
            actions, not knowing about each other could share the same key
            if they are enabled in different contexts. To implement this it
            would be needed to have more keystroke to action mappings. For
            example for each component. This is possible, but a bit complicated
            especially with respect to multi keystroke shortcuts - as found out
            during the <a href="http://openide.netbeans.org/tutorial/reviews/opinions_64621.html" shape="rect">multikeys support review</a>
            there is a need to for all the keystroke mappings to always share 
            the common prefix. As this seems to be complicated, this is not going to
            be done for 5.1.
            <!-- #19485 [TBD, jrechtacek] - Use InputMap for handling of global shorcuts -->
            
        </p>
    
    
    <!--
        First see the <a href="org/openide/actions/doc-files/api.html">API description</a>. Here is just
    a list of frequently asked or interesting questions slowly expanding as
    people ask them:
    
    <h3>Actions faq:</h3>
    
    <usecase id="context-action-shortcuts" name="How to define configurable Shortcut for Component based shortcut?" >
<em><b>Q:</b>
The usual Swing way of defining Actions for your component is to create an Action instance and put it into the Input and Action maps of your component.
However how to make this Action's shortcut configurable from the Tools/Keyboard Shortcuts dialog?</em>
<p>
In order for the action to show up in Keyboards Shortcut dialog you need the action defined in the 
layer file under "Actions" folder and have the shortcut defined there under "Keymaps/&lt;Profile Name&gt;" linking to your action.
</p>
<pre>
    &lt;folder name="Actions" &gt;
        &lt;folder name="Window"&gt;
            &lt;file name="org-netbeans-core-actions-PreviousViewCallbackAction.instance"/&gt;
        &lt;/folder&gt;
    &lt;/folder&gt;

    &lt;folder name="Keymaps"&gt;
        &lt;folder name="NetBeans"&gt;
            &lt;file name="S-A-Left.shadow"&gt;
                &lt;attr name="originalFile" stringvalue="Actions/Window/org-netbeans-core-actions-PreviousViewCallbackAction.instance"/&gt;
            &lt;/file&gt;
        &lt;/folder&gt;
    &lt;/folder&gt;
</pre>
<p>
The mentioned Action has to be a subclass of <code>org.openide.util.actions.CallbackSystemAction</code>. It does not necessarily has to 
perform the action, it's just a placeholder for linking the shortcut. You might want to override it's <code>getActionMapKey()</code> and give it a 
reasonable key.
</p>
<p>
The actual action that does the work in your component (preferably a simple Swing <code>javax.swing.Action</code>)
is to be put into your <code>TopComponent</code>'s <code>ActionMap</code>. The key for the <code>ActionMap</code> 
has to match the key defined in the global action's <code>getActionMapKey()</code> method.
</p>
<pre>
        getActionMap().put("PreviousViewAction", new MyPreviousTabAction());
</pre>
<p>
This way even actions from multiple <code>TopComponent</code>s with the same gesture (eg. "switch to next tab") can share the same configurable shortcut.
</p>
<p>
Note: Don't define your action's shortcut and don't put it into any of the <code>TopComponent</code>'s
<code>javax.swing.InputMap</code>. Otherwise the component would not pick up the changed shortcut from the
global context.
</p>

    </usecase>
    
    -->

<p></p>
<font color="gray"><b><a name="answer-arch-time">Question (arch-time)</a>:</b><em>
            What are the time estimates of the work?
            
        </em></font>
<p></p>
<b>Answer:</b>
    
<p>
    The main goal - e.g. no need to rely on 
    <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-util/org/openide/util/actions/SystemAction.html" shape="rect">
        SystemAction
    </a> - has to be achived in one release. Best in <b>promo-g</b>.
    The API is designed in extensible way and covered by tests, so 
    incremental evolution will be possible in every future release.
    </p>
 
<p></p>
<font color="gray"><b><a name="answer-arch-quality">Question (arch-quality)</a>:</b><em>
            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?
            
        </em></font>
<p></p>
<b>Answer:</b>
    
<p>
    Obviously there is a lot of unit tests for the behaviour of 
    actions created using API of this module. There are few indicators
    that are determining if the quality is good:
    </p>
    
<ul>
        
<li>the provided functionality is working as expected - e.g. test coverage is good enough and tests passes</li>
        
<li>the modules is capably enough to replace 90% of usages of the historic APIs</li>
        
<li>ProjectUI API Actions (de facto pioneers of the new way of writing actions, just not general
        enough) can be migrated to new infrastructure</li>
        
<li>Declarative registrations lowers # of loaded classes and help startup time</li>
        
<li>API follows the Swing patterns and allows easy integration of existing Swing Actions</li>
        
<li>API support can change all its templates to this new API</li>
    
</ul>
 
<p></p>
<font color="gray"><b><a name="answer-arch-where">Question (arch-where)</a>:</b><em>
            Where one can find sources for your module?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
<p>
            The sources for the module are in <a href="http://www.netbeans.org" shape="rect">NetBeans</a>
            CVS in 
            <a href="http://www.netbeans.org/source/browse/openide/actions" shape="rect">openide/actions</a>
            directory.
        </p>
</p>
 
</ul>
    
<hr>
<h2>Project and platform dependencies</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-dep-nb">Question (dep-nb)</a>:</b><em>
            What other NetBeans projects and modules does this one depend on?
            
        </em></font>
<p></p>
<b>Answer:</b>
    <a href="#java-UtilitiesAPI">UtilitiesAPI</a> the only one API that is really required.
</ul>
</p>
</p>
</p>
<p></p>
<font color="gray"><b><a name="answer-dep-non-nb">Question (dep-non-nb)</a>:</b><em>
            What other projects outside NetBeans does this one depend on?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-dep-platform">Question (dep-platform)</a>:</b><em>
            On which platforms does your module run? Does it run in the same
            way on each?
            
        </em></font>
<p></p>
<b>Answer:</b>
100% pure Java. It should run anywhere.
<p></p>
<font color="gray"><b><a name="answer-dep-jre">Question (dep-jre)</a>:</b><em>
            Which version of JRE do you need (1.2, 1.3, 1.4, etc.)?
            
        </em></font>
<p></p>
<b>Answer:</b>
It uses JRE 1.3.
<p></p>
<font color="gray"><b><a name="answer-dep-jrejdk">Question (dep-jrejdk)</a>:</b><em>
            Do you require the JDK or is the JRE enough?
        </em></font>
<p></p>
<b>Answer:</b>
JRE is enough.
</ul>

    
<hr>
<h2>Deployment</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-deploy-jar">Question (deploy-jar)</a>:</b><em>
            Do you deploy just module JAR file(s) or other files as well?
            
        </em></font>
<p></p>
<b>Answer:</b>
    Possible. Of course.
<p></p>
<font color="gray"><b><a name="answer-deploy-nbm">Question (deploy-nbm)</a>:</b><em>
            Can you deploy an NBM via the Update Center?
            
        </em></font>
<p></p>
<b>Answer:</b>
Yes.
<p></p>
<font color="gray"><b><a name="answer-deploy-shared">Question (deploy-shared)</a>:</b><em>
            Do you need to be installed in the shared location only, or in the user directory only,
            or can your module be installed anywhere?
            
        </em></font>
<p></p>
<b>Answer:</b>
Most of the platform cluster depends on this library so it very likely should be 
in shared location.
<p></p>
<font color="gray"><b><a name="answer-deploy-packages">Question (deploy-packages)</a>:</b><em>
            Are packages of your module made inaccessible by not declaring them
            public?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
Sure.
<p></p>
<font color="gray"><b><a name="answer-deploy-dependencies">Question (deploy-dependencies)</a>:</b><em>
            What do other modules need to do to declare a dependency on this one?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for deploy-dependencies
  </p>
 
</ul>
    
    
<hr>
<h2>Compatibility with environment</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-compat-i18n">Question (compat-i18n)</a>:</b><em>
            Is your module correctly internationalized?
            
        </em></font>
<p></p>
<b>Answer:</b>
Yes.
<p></p>
<font color="gray"><b><a name="answer-compat-standards">Question (compat-standards)</a>:</b><em>
            Does the module implement or define any standards? Is the 
            implementation exact or does it deviate somehow?
        </em></font>
<p></p>
<b>Answer:</b>
Before the Actions was build on <code>org.openide.util.actions.SystemAction</code>, this
was recently changed that Actions supports <code>javax.swing.Action</code> which
is java API standard, and Actions will be improving towards this more and more.
<p></p>
<font color="gray"><b><a name="answer-compat-version">Question (compat-version)</a>:</b><em>
            Can your module coexist with earlier and future
            versions of itself? Can you correctly read all old settings? Will future
            versions be able to read your current settings? Can you read
            or politely ignore settings stored by a future version?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
Yes up to now it is supposed to be compatible with older versions.
</ul>
    
    
<hr>
<h2>Access to resources</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-resources-file">Question (resources-file)</a>:</b><em>
            Does your module use <code>java.io.File</code> directly?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-resources-layer">Question (resources-layer)</a>:</b><em>
            Does your module provide own layer? Does it create any files or
            folders in it? What it is trying to communicate by that and with which 
            components?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
No in fact. Just concrete action implementation provided by this module
are typically used in xml layers.
<p></p>
<font color="gray"><b><a name="answer-resources-read">Question (resources-read)</a>:</b><em>
            Does your module read any resources from layers? For what purpose?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
There are special folders containing actions in xml layers.
<ul>

<li>
<em>Menu</em> contains actions which are present in menu.</li>

<li>
<em>Toolbars</em> contains actions which will be present in toolbars.</li>

<li>
<em>Shortcuts</em> contains actions which will have assigned shortcuts.</li>

<li>
<em>Actions</em> contains actions which are possible to manipulate with (via Options).</li>

</ul>

<em>Note:</em> Those layers are not necessarily read by Actions module. Probably 
it belongs to <em>Window system module</em>.
<p></p>
<font color="gray"><b><a name="answer-resources-mask">Question (resources-mask)</a>:</b><em>
            Does your module mask/hide/override any resources provided by other modules in
            their layers?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
</ul>

    
    
<hr>
<h2>Lookup of components</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-lookup-lookup">Question (lookup-lookup)</a>:</b><em>
            Does your module use <code>org.openide.util.Lookup</code>
            or any similar technology to find any components to communicate with? Which ones?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for lookup-lookup
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-lookup-register">Question (lookup-register)</a>:</b><em>
            Do you register anything into lookup for other code to find?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for lookup-register
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-lookup-remove">Question (lookup-remove)</a>:</b><em>
            Do you remove entries of other modules from lookup?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for lookup-remove
  </p>
 
</ul>

    
    <!-- classification of interfaces -->
    
    <!-- package names -->
    
    
    
<hr>
<h2>Execution Environment</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-exec-property">Question (exec-property)</a>:</b><em>
            Is execution of your code influenced by any environment or
            Java system (<code>System.getProperty</code>) property?
            
            
        </em></font>
<p></p>
<b>Answer:</b>


<p></p>
<font color="gray"><b><a name="answer-exec-component">Question (exec-component)</a>:</b><em>
            Is execution of your code influenced by any (string) property
            of any of your components?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
    
    <!-- JST-PENDING
There are used three values (via <code>Action.getValue()</code>).
<ul>
    <li><api name="OpenIDE-Transmodal-Action" group="property" category="devel" type="export">Inidicates action can be performed
    (typicaly via shortcut) even when dialog is popped out (modal or modeless).</api></li>
    <li><api name="delegates" group="property" category="devel" type="export">Used internaly in <code>PasteAction</code> delegate action
    which serves to pass an array of <code>PasteType</code> or <code>Action</code> to global instance (it is the only one
    which actually performs paste operation).</api></li>
    <li><api name="iconBase" group="property" category="devel" type="export">Used in companion to Actions.SMALL_ICON. Because there
    is no way to specify values for other types of icons the value of "iconBase" is used
    to construct the resource names of disabled, pressed and rollover icons. The value is
    expected to contain a resource path of the normal icon. Strings "_pressed",
    "_disabled" and "_rollover" are inserted before the suffix when searching for
    the other types of icons.</api></li>
    <li><api name="noIconInMenu" group="property" category="devel" type="export"> 
    Allowed value <code>Boolean.TRUE</code>.
    Influences the display of the action in the main menu, the item will have no icon there. Works for Actions that don't define custom MenuPresenter.
    </api></li>    
    <li><api name="PreferredIconSize" group="property" category="devel" type="export">
    Used to support 24x24 icons in toolbars. If toolbar button has client property "PreferredIconSize"
    set to Integer(24) button tries to load icon with name "iconBase" + "24" eg. "cut24.gif".
    Strings "_pressed","_disabled" and "_rollover" are inserted before the suffix when searching for
    the other types of icons eg.:"cut24_pressed.gif".</api></li>
    <li>
        <api name="waitFinished" group="property" category="friend" type="export">
             There is a new contract established between the caller of an action that
             allows mutual communication and possible synchronous execution even for 
             actions that by default perform their operations asynchronously. If the
             action's <code>actionPeformed</code> method is passed <code>ActionEvent</code>
             with command <q>waitFinished</q> the action shall be executed synchronously.
             The code:
             <pre>
             action.actionPerformed (new ActionEvent (this, 0, "waitFinished"))
             </pre>
             shall be executed synchronously, even if the action by default runs asynchronously.
             All asynchronous actions are asked to obey this contract, <code>CallableSystemAction</code>
             does it by default. However this contract is defined as friend one 
             and may be abandoned in future.
        </api>
    </li>
    
    
</ul>

    -->


<p></p>
<font color="gray"><b><a name="answer-exec-ant-tasks">Question (exec-ant-tasks)</a>:</b><em>
            Do you define or register any ant tasks that other can use?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   No ant tasks.
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-exec-classloader">Question (exec-classloader)</a>:</b><em>
            Does your code create its own class loader(s)?
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-exec-reflection">Question (exec-reflection)</a>:</b><em>
            Does your code use Java Reflection to execute other code?
            
        </em></font>
<p></p>
<b>Answer:</b>


<p></p>
<font color="gray"><b><a name="answer-exec-privateaccess">Question (exec-privateaccess)</a>:</b><em>
            Are you aware of any other parts of the system calling some of 
            your methods by reflection?
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-exec-process">Question (exec-process)</a>:</b><em>
            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?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   Not at all.
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-exec-introspection">Question (exec-introspection)</a>:</b><em>
            Does your module use any kind of runtime type information (<code>instanceof</code>,
            work with <code>java.lang.Class</code>, etc.)?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for exec-introspection
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-exec-threading">Question (exec-threading)</a>:</b><em>
            What threading models, if any, does your module adhere to?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   Most of the action manipulation shall happen only on AWT event thread. This
   is going to be enforced by asserts. The constructor can however be called
   outside of the AWT event thread to lower the load during the action
   creation and also certain attributes like icon and context less name 
   can also be got from other threads.
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-security-policy">Question (security-policy)</a>:</b><em>
            Does your functionality require modifications to the standard policy file?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for security-policy
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-security-grant">Question (security-grant)</a>:</b><em>
            Does your code grant additional rights to some other code?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for security-grant
  </p>
 
</ul>
    
    
<hr>
<h2>Format of files and protocols</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-format-types">Question (format-types)</a>:</b><em>
            Which protocols and file formats (if any) does your module read or write on disk,
            or transmit or receive over the network? Do you generate an ant build script?
            Can it be edited and modified? 
            
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for format-types
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-format-dnd">Question (format-dnd)</a>:</b><em>
            Which protocols (if any) does your code understand during Drag &amp; Drop?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for format-dnd
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-format-clipboard">Question (format-clipboard)</a>:</b><em>
            Which data flavors (if any) does your code read from or insert to
            the clipboard (by access to clipboard on means calling methods on <code>java.awt.datatransfer.Transferable</code>?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for format-clipboard
  </p>
 
</ul>

    
    
<hr>
<h2>Performance and Scalability</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-perf-startup">Question (perf-startup)</a>:</b><em>
            Does your module run any code on startup?
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-perf-exit">Question (perf-exit)</a>:</b><em>
            Does your module run any code on exit?
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-exit
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-perf-scale">Question (perf-scale)</a>:</b><em>
            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?
            
        </em></font>
<p></p>
<b>Answer:</b>
This should be irrelevant, as far as I know, Actions shouldn't use any collections
of data or something like that. One exception I know is global keymap implementation
which scales linear.
<p></p>
<font color="gray"><b><a name="answer-perf-limit">Question (perf-limit)</a>:</b><em>
            Are there any hard-coded or practical limits in the number or size of
            elements your code can handle?
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-limit
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-perf-mem">Question (perf-mem)</a>:</b><em>
            How much memory does your component consume? Estimate
            with a relation to the number of windows, etc.
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-mem
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-perf-wakeup">Question (perf-wakeup)</a>:</b><em>
            Does any piece of your code wake up periodically and do something
            even when the system is otherwise idle (no user interaction)?
        </em></font>
<p></p>
<b>Answer:</b>
No. At least I do not know about that.
<p></p>
<font color="gray"><b><a name="answer-perf-progress">Question (perf-progress)</a>:</b><em>
            Does your module execute any long-running tasks?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-perf-huge_dialogs">Question (perf-huge_dialogs)</a>:</b><em>
            Does your module contain any dialogs or wizards with a large number of
            GUI controls such as combo boxes, lists, trees, or text areas?
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-huge_dialogs
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-perf-menus">Question (perf-menus)</a>:</b><em>
            Does your module use dynamically updated context menus, or
            context-sensitive actions with complicated and slow enablement logic?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-menus
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-perf-spi">Question (perf-spi)</a>:</b><em>
            How the performance of the plugged in code will be enforced?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-spi
  </p>
 
</ul>
    
    
    <!-- security -->
    <!-- recovery -->
    

</api-questions>





 

 

 

 



  













<!-- Question: compat-i18n

     <question id="compat-i18n">
            Is your module correctly internationalized?
            <hint>
            Correct internationalization means that it obeys instuctions 
            at <a href="http://www.netbeans.org/devhome/docs/i18n/index.html">
            NetBeans I18N pages</a>.
            </hint>
        </question>
-->




<!-- Question: compat-standards

     <question id="compat-standards">
            Does the module implements or defines any standards? Is the 
            implementation exact or it deviates somehow?
        </question>
-->




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




<!-- Question: dep-jre

     <question id="dep-jre">
            Which version of JRE you need (1.2, 1.3, 1.4, etc.)?
            <hint>
            It is expected that if your module runs on 1.x that it will run 
            on 1.x+1 if no, state that please. Also describe here cases where
            you run different code on different versions of JRE and why.
            </hint>
        </question>
-->




<!-- Question: dep-jrejdk

     <question id="dep-jrejdk">
            Do you require JDK or is JRE enough?
        </question>
-->




<!-- Question: dep-nb

     <question id="dep-nb">
            What other NetBeans projects this one depends on?
            <hint>
            If you want, describe such projects as imported API using
            the <code>&lt;api name="identification" type="import or export" category="stable" url="where is the description" /&gt;</code>
            </hint>
        </question>
-->




<!-- 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
            (see <a href="http://libs.netbeans.org">libraries</a>) and
            it is prefered to use this approach when more modules may
            depend on such third-party library.
            </hint>
        </question>
-->




<!-- Question: dep-platform

     <question id="dep-platform">
            On which platforms your module run? Any? Does it run in the same
            way?
            <hint>
            If your module is using JNI or deals with special differences of
            OSes like filesystems, etc. please describe here what they are.
            </hint>
        </question>
-->




<!-- Question: deploy-jar

     <question id="deploy-jar">
            Do you deploy just module JAR file(s) or some other files?
            <hint>
            If your module consist just from one module JAR file, just confirm that.
            If it uses more than one JAR, describe where there are located, how
            they refer to each other. 
            If it consist of module JAR(s) and other files, please describe
            what is their purpose, why other files are necessary. Please 
            make sure that installation/deinstallation leaves the system 
            in state as it was before installation.
            </hint>
        </question>
-->



<!--
        <question id="deploy-dependencies" when="final">
            What do other modules need to do to declare a dependency on this one?
            <hint>
                Provide a sample of the actual lines you would add to a module manifest
                to declare a dependency, for example using OpenIDE-Module-Module-Dependencies
                or OpenIDE-Module-Requires. You may use the magic token 6.5
                to represent the current specification version of the module.
            </hint>
        </question>
-->
 


<!-- Question: deploy-nbm

     <question id="deploy-nbm">
            Can you deploy NBM via AutoUpdate center?
            <hint>
            If not why?
            </hint>
        </question>
-->




<!-- 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
            whenever possible (<a href="http://www.netbeans.org/download/apis/org/openide/doc-files/upgrade.html#3.4-public-packages">
            public packages
            </a>). 
            </hint>
        </question>
-->




<!-- Question: deploy-shared

     <question id="deploy-shared">
            Do you need to be installed in shared location or only in user directory?
            <hint>
            Installation location shall not matter, if it does explain why.
            </hint>
        </question>
-->




<!-- Question: exec-classloader

     <question id="exec-classloader">
            Does your code uses own classloader?
            <hint>
            A bit unusual. Please explain why and what for.
            </hint>
        </question>
-->




<!-- Question: exec-component

     <question id="exec-component">
            Is execution of your code influenced by (string) property
            of any of your components?
            
            <hint>
            Often <code>JComponent.getClientProperty</code>, <code>Action.getValue</code>
            or <code>PropertyDescriptor.getValue</code>, etc. are used to influence
            a behaviour of some code. This of course forms an interface that should
            be documented. Also if one depends on some interface that an object
            implements (<code>component instanceof Runnable</code>) that forms an
            API as well.
            </hint>
        </question>
-->




<!-- Question: exec-privateaccess

     <question id="exec-privateaccess">
            Are you aware of any other part 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>
-->




<!-- Question: exec-property

     <question id="exec-property">
            Is execution of your code influenced by any environment of
            system (<code>System.getProperty</code>) property?
            
            <hint>
            If there is a property that can change the behaviour of your 
            code, somebody will likely use it. You should describe what it does 
            and the stability category of this API. You may use
            <PRE>
                &lt;property name="id" category="private" &gt;
                    description of the property, where it is used, what it influence, etc.
                &lt;/property&gt;            
            </PRE>
            </hint>
        </question>
-->




<!-- Question: exec-reflection

     <question id="exec-reflection">
            Does your code uses java.lang.reflect to execute some other code?
            <hint>
            This usually indicates a missing or unsufficient 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>
-->



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




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




<!-- Question: perf-startup

     <question id="perf-startup">
            Does your module executes anything on startup?
        </question>
-->




<!-- Question: perf-wakeup

     <question id="perf-wakeup">
            Is any piece of your code waking up periodically?
        </question>
-->




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




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




<!-- Question: resources-mask

     <question id="resources-mask">
            Does your module mask/hide/override any resource provided by another one in
            module layer? 
            
            <hint>
            If you mask a file provided by another module, you probably depend
            on that and do not want the other module to (for example) change
            the file's name. That module shall thus make that file available as an API
            of some stability category.
            </hint>
        </question>
-->




<!-- Question: resources-read

     <question id="resources-read">
            Does your module read any resources from layers? For what purpose?
            
            <hint>
            As this is some kind of intermodule dependency, it is a kind of API.
            Please describe it and clasify according to 
            <a href="http://openide.netbeans.org/tutorial/api-design.html#categories">
            common stability categories</a>.
            </hint>
        </question>
-->








 



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



 

 




<!--
        <question id="format-clipboard" when="impl">
            Which data flavors (if any) does your code read from or insert to
            the clipboard (by access to clipboard on means calling methods on <code>java.awt.datatransfer.Transferable</code>?
            
            <hint>
            Often Node's deal with clipboard by usage of <code>Node.clipboardCopy, Node.clipboardCut and Node.pasteTypes</code>.
            Check your code for overriding these methods.
            </hint>
        </question>
-->
 



<!--
        <question id="format-dnd" when="impl">
            Which protocols (if any) does your code understand during Drag &amp; Drop?
            <hint>
            Often Node's deal with clipboard by usage of <code>Node.drag, Node.getDropType</code>. 
            Check your code for overriding these methods. Btw. if they are not overridden, they
            by default delegate to <code>Node.clipboardCopy, Node.clipboardCut and Node.pasteTypes</code>.
            </hint>
        </question>
-->
 



<!--
        <question id="format-types" when="impl">
            Which protocols and file formats (if any) does your module read or write on disk,
            or transmit or receive over the network? Do you generate an ant build script?
            Can it be edited and modified? 
            
            <hint>
            <p>
            Files can be read and written by other programs, modules and users. If they influence
            your behaviour, make sure you either document the format or claim that it is a private
            api (using the &lt;api&gt; tag). 
            </p>
            
            <p>
            If you generate an ant build file, this is very likely going to be seen by end users and
            they will be attempted to edit it. You should be ready for that and provide here a link
            to documentation that you have for such purposes and also describe how you are going to
            understand such files during next release, when you (very likely) slightly change the 
            format.
            </p>
            </hint>
        </question>
-->
 



<!--
        <question id="lookup-lookup" when="init">
            Does your module use <code>org.openide.util.Lookup</code>
            or any similar technology to find any components to communicate with? Which ones?
            
            <hint>
            Please describe the interfaces you are searching for, where 
            are defined, whether you are searching for just one or more of them,
            if the order is important, etc. Also classify the stability of such
            API contract. For that use &lt;api group=&amp;lookup&amp; /&gt; tag.
            </hint>
        </question>
-->
 



<!--
        <question id="lookup-register" when="final">
            Do you register anything into lookup for other code to find?
            <hint>
            Do you register using layer file or using <code>META-INF/services</code>?
            Who is supposed to find your component?
            </hint>
        </question>
-->
 



<!--
        <question id="lookup-remove" when="final">
            Do you remove entries of other modules from lookup?
            <hint>
            Why? Of course, that is possible, but it can be dangerous. Is the module
            your are masking resource from aware of what you are doing?
            </hint>
        </question>
-->
 



<!--
        <question id="perf-exit" when="final">
            Does your module run any code on exit?
        </question>
-->
 



<!--
        <question id="perf-huge_dialogs" when="final">
            Does your module contain any dialogs or wizards with a large number of
            GUI controls such as combo boxes, lists, trees, or text areas?
        </question>
-->
 



<!--
        <question id="perf-limit" when="init">
            Are there any hard-coded or practical limits in the number or size of
            elements your code can handle?
        </question>
-->
 



<!--
        <question id="perf-mem" when="final">
            How much memory does your component consume? Estimate
            with a relation to the number of windows, etc.
        </question>
-->
 



<!--
        <question id="perf-menus" when="final">
            Does your module use dynamically updated context menus, or
            context-sensitive actions with complicated and slow enablement logic?
            <hint>
                If you do a lot of tricks when adding actions to regular or context menus, you can significantly
                slow down display of the menu, even when the user is not using your action. Pay attention to
                actions you add to the main menu bar, and to context menus of foreign nodes or components. If
                the action is conditionally enabled, or changes its display dynamically, you need to check the
                impact on performance. In some cases it may be more appropriate to make a simple action that is
                always enabled but does more detailed checks in a dialog if it is actually run.
            </hint>
        </question>
-->
 



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



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



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


</api-answers>
<hr>
<p><span class="footnote">Built on December 13 2005.&nbsp;&nbsp;|&nbsp;&nbsp;Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.</span></p>
</body>
</html>

Attachment #28332
The version of arch document as of 2005, Jan 10	text/html	2006-01-10 11:32:27 UTC	93.82 KB	no flags	Details

<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Actions - NetBeans Architecture Questions</title>
</head>
<body>
<h1>NetBeans Architecture Answers for Actions module</h1>
<ul>
<li>
<b>Author:</b> jtulach@netbeans.org</li>
<li>
<b>Answers as of:</b> 9.1.2006</li>
<li>
<b>Answers for questions version:</b> 1.26</li>
<li>
<b>Latest available version of questions:</b> 1.26</li>
</ul>
<hr>
<h2>Interfaces table</h2>
<a name="group-property">
<h5>Group of property interfaces</h5>
</a>
<table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%">
<tr>
<td>
<table border="0" cellpadding="3" cellspacing="1" width="100%">
<tr class="tablersh">
<td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td>
</tr>
<tr class="tabler">
<td>SystemFileSystem.icon24</td><td>Exported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-stable">Stable</a></td><td><a name="property-SystemFileSystem.icon24">
<p></p>As actions need also 24x24 color icon, there is additional
        support for specifying it. Just use 
        &lt;attr name="SystemFileSystem.icon24" urlvalue="..." /&gt; in the
        layer to provide definition of 24x24 icon for the action.
        <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>defaultAction</td><td>Exported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-stable">Stable</a></td><td><a name="property-defaultAction">
<p></p>
                that is going to be associated on the <a href="@JDK@/javax/swing/JMenuItem.html" shape="rect">JMenuItem</a>
                created as a presenter for the action.
            <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>ActionMapKeys</td><td>Exported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-stable">Stable</a></td><td><a name="property-ActionMapKeys">
<p></p>
                certain keys has been published by the platform and modules can use
                them to register their own implementation in action maps of their 
                components:
                <ul>
                    
<li>
<code>"cloneWindow"</code> - an action to be executed when a top component is to be cloned</li>
                    
<li>
<code>"closeWindow"</code> - an action when a view is about to be closed</li>
                    
<li>
<code>DefaultEditorKit.copyAction</code> - copy action handler</li>
                    
<li>
<code>DefaultEditorKit.cutAction</code> - cut action handler</li>
                    
<li>
<code>"delete"</code> - delete action handler</li>
                    
<li>
<code>DefaultEditorKit.pasteAction</code> - paste action handler</li>
                    
<li>
<code>"jumpNext"</code> - when a next element shall be selected</li>
                    
<li>
<code>"jumpPrev"</code> - when a previous element shall be selected</li>
                
</ul>
            
<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>AcceleratorKey</td><td>Exported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-stable">Stable</a></td><td><a name="property-AcceleratorKey">
<p></p>
            the value of <code>Action.ACCELERATOR_KEY</code> needs to be shared
            between all instances that are created by the same factory, using
            the same arguments.
        <p></p>
</a></td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<a name="group-java">
<h5>Group of java interfaces</h5>
</a>
<table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%">
<tr>
<td>
<table border="0" cellpadding="3" cellspacing="1" width="100%">
<tr class="tablersh">
<td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td>
</tr>
<tr class="tabler">
<td>ProgressAPI</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-stable">Stable</a></td><td><a name="java-ProgressAPI"><a href="@org-netbeans-api-progress@/overview-summary.html">
                            .../overview-summary.html</a>
<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>UtilitiesAPI</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-official">Official</a></td><td><a name="java-UtilitiesAPI"><a href="@org-openide-util@/overview-summary.html">@org-openide-util@/overview-summary.html</a>
<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.util</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.util"><a href="@org-openide-util@/overview-summary.html">@org-openide-util@/overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.nodes</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.nodes"><a href="@org-openide-nodes@/overview-summary.html">
                            .../overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.awt</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.awt"><a href="@org-openide-awt@/overview-summary.html">@org-openide-awt@/overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.5
                    is required.
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.options</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.options"><a href="@org-openide-options@/overview-summary.html">
                            .../overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.text</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.text"><a href="@org-openide-text@/overview-summary.html">@org-openide-text@/overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.explorer</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.explorer"><a href="@org-openide-explorer@/overview-summary.html">
                            .../overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.dialogs</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.dialogs"><a href="@org-openide-dialogs@/overview-summary.html">
                            .../overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.windows</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.windows"><a href="@org-openide-windows@/overview-summary.html">
                            .../overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>ActionsEquality</td><td>Exported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-stable">Stable</a></td><td><a name="java-ActionsEquality">
<p></p>
            It depends implementation of <code>Action.equals(Object)</code> and
            <code>Action.hashCode()</code> methods. The implementation influences 
            the behaviour
            of actions on multi selections - e.g. when a popup menu for more
            than one node is invoked, only actions available on all of them 
            (tested by <code>equals</code> method) are shown. Generally
            actions are equal if they are <em>created with the same factory method
            providing the same arguments and they are assigned to the 
            same <a href="@org-openide-util@/org/openide/util/Lookup.html" shape="rect">context</a>
            </em>.
        <p></p>
</a></td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<!--
                Sun Public License Notice

The contents of this file are subject to the Sun Public License
Version 1.0 (the "License"). You may not use this file except in
compliance with the License. A copy of the License is available at
http://www.sun.com/

The Original Code is NetBeans. The Initial Developer of the Original
Code is Sun Microsystems, Inc. Portions Copyright 1997-2005 Sun
Microsystems, Inc. All Rights Reserved.
-->
<api-answers author="jtulach@netbeans.org" module="Actions" question-version="1.26">

  
<!--
                Sun Public License Notice

The contents of this file are subject to the Sun Public License
Version 1.0 (the "License"). You may not use this file except in
compliance with the License. A copy of the License is available at
http://www.sun.com/

The Original Code is NetBeans. The Initial Developer of the Original
Code is Sun Microsystems, Inc. Portions Copyright 1997-2004 Sun
Microsystems, Inc. All Rights Reserved.
-->

<!--
    Author     : Jaroslav Tulach
    Description: Questions that should be answered in order to make better API

    No PUBLIC or SYSTEM IDs defined currently.
-->


<!--
                        *** ATTENTION EDITORS ***
Please increment the 'version' field of <api-questions> whenever you make a
semantic change: adding a new question or significantly changing the meaning of
an old one. Changing this field ensures that arch pages answering the old version
print a warning during Javadoc generation. If you only change hints or make small
edits in the text of a question, you need not change the version number.

Also rerun openide/www/tutorial/build.xml#question when you are done and commit
openide/www/tutorial/questions.html.
-->

<api-questions version="1.26" xml:base="file:/doma/jarda/netbeans-src/nbbuild/antsrc/org/netbeans/nbbuild/Arch-api-questions.xml">
    
<hr>
<h2>General Information</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-arch-what">Question (arch-what)</a>:</b><em>
            What is this project good for?
            
        </em></font>
<p></p>
<b>Answer:</b>
    
<p>
    This module provides support for creation of actions, supports and
    takes care of their presentation in global menus, toolbars and popup 
    menu. By using methods and other APIs from this module one shall be
    able to easily create instances of <a href="@JDK@/javax/swing/Action.html" shape="rect">javax.swing.Action</a>
    which are ready to use in the NetBeans platform.
    </p>

<p></p>
<font color="gray"><b><a name="answer-arch-overall">Question (arch-overall)</a>:</b><em>
            Describe the overall architecture. 
            
        </em></font>
<p></p>
<b>Answer:</b>
    
<p>
    The architecture of this module builds on existing NetBeans Platform
    abstractions that has been proven to be useful. 
    This lowers the amount of changes in comparition
    from NetBeans 5.0 and concentrates them into relatively small, isolated
    area. The basic building block is 
    <a href="@org-openide-util@/org/openide/util/Utilities.html#actionsGlobalContext()" shape="rect">
        Utilities.actionGlobalContext()
    </a> and 
    <a href="@org-openide-util@/org/openide/util/ContextAwareAction.html" shape="rect">
        ContextAwareAction
    </a> interface. These were introduced to solve focus problems when 
    creating pop up menus on window managers with other then click-to-focus
    behaviours and seem to work quite well.
    </p>
    
    
<p>
    One of the most important goals is to remove the need to work with
    historic <a href="@org-openide-util@/org/openide/util/actions/SystemAction.html" shape="rect">
        SystemAction
    </a> and subclasses. Beyond the fact the they are instances of
    <a href="@org-openide-util@/org/openide/util/SharedClassObject.html" shape="rect">
        SharedClassObject
    </a> and such they have limited, complex and not very useful lifecycle
    management, they also rely on old and currently already obsolete concepts
    like <a href="@org-openide-nodes@/org/openide/nodes/Node.Cookie.html" shape="rect">Node.Cookie</a>.
    By using this module one does not need to care about the 
    <a href="@org-openide-util@/org/openide/util/actions/SystemAction.html" shape="rect">
        SystemAction
    </a> at all. A knowledge and understanding of 
    <a href="@org-openide-nodes@/org/openide/nodes/Node.Cookie.html" shape="rect">Node.Cookie</a>
    is required no more as well.
    </p>
    
    
<h5>Out Of Scope</h5>
    
    
<p>
        Part of overall description is also list of things that are not addressed
        by the effort. So it is wise to state that the actions module does not 
        addresses following issues:
    </p>
    
    
<ul>
        
<li>Do not change the concept of layers and system file system. 
            E.g. no namings, registries, etc. 
            Build on what is available right now.
        </li>
    
</ul>
 
<p></p>
<font color="gray"><b><a name="answer-arch-usecases">Question (arch-usecases)</a>:</b><em>
            
        
            Describe the main <a href="http://openide.netbeans.org/tutorial/api-design.html#usecase" shape="rect">
            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?
        </em></font>
<p></p>
<b>Answer:</b>
    
<h4>Defining An Action Placeholder</h4>
    
<p>
        The new design of actions framework is following the Swing JDK 1.3
        design as close as possible. That is why it is going to follow the
        <a href="@JDK@/javax.swing.InputMap" shape="rect">InputMap</a> and
        <a href="@JDK@/javax.swing.ActionMap" shape="rect">ActionMap</a> separation.
    </p>    
    
<p>
        The base constraint for this is to separate definition of action
        <em>key</em> from the actual definition of an action. The 
        key is then going to be put into a global 
        <a href="@JDK@/javax.swing.InputMap" shape="rect">InputMap</a>
        and assigned to a <a href="@JDK@/javax.swing.KeyStroke" shape="rect">KeyStroke</a>,
        while the actual action to be invoked is then put into an active
        <a href="@JDK@/javax.swing.ActionMap" shape="rect">ActionMap</a> and assigned
        to the specified key.
    </p>
    
    
<p>
        To achieve such state and also handle backward compatibility with older actions
        definition, all actions created by this module support the notion
        of a key and communicate with the whole system on registration 
        of the key and default action implementation into global
        <a href="@JDK@/javax.swing.InputMap" shape="rect">InputMap</a> and
        <a href="@JDK@/javax.swing.ActionMap" shape="rect">ActionMap</a>.
    </p>
    
    
<p>
        The basic pattern is based on layer definition inside the <code>Actions/</code>
        folder and its subfolders in layer where one can creates an action
        instance using one of the factories methods and assigns it a key:
    </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.spi.actions.Factory.oneOfFactoryMethods" /&gt;
    &lt;attr name="key" stringvalue="your.module.Key" &gt;
    &lt;attr name="defaultCreate" newvalue="your.module.prefix.YourAction" &gt;
  &lt;/file&gt;
</pre>
    
<p>
        The above snippet creates a registration of an action that can
        be then refered from <code>Menu</code>, <code>Toolbar</code>, <code>Shortcuts</code>
        folders and by default delegates to an active 
        <a href="@JDK@/javax.swing.ActionMap" shape="rect">ActionMap</a> to find out 
        the right action delegate to perform the operation - the value of the 
        <code>key</code> attribute is used to ask the 
        <a href="@JDK@/javax.swing.ActionMap" shape="rect">ActionMap</a> for the action delegate.
    </p>
    
    
<p>
        Beyond this <q>generic delegator</q> the usual action definition 
        also includes voluntary definition of a default implementation. E.g.
        some action that gets invoked if nobody provides a better implementation
        and registers it to the key into its own <a href="@JDK@/javax.swing.ActionMap" shape="rect">ActionMap</a>.
        Such default implementation is taken from a value of 
        <code>defaultCreate</code> attribute and can be instance of 
        existing class or <code>boolvalue="true"</code> to take
        the default provided by the <code>oneOfFactoryMethods</code>
        as discussed in next usecases. This default implementation
        is put into global <a href="@JDK@/javax.swing.ActionMap" shape="rect">ActionMap</a>
        which is by default parent map of any 
        <a href="@org-openide-windows@/org/openide/windows/TopComponent.html" shape="rect">TopComponent</a>.getActionMap()
        and as such serves as a fallback.
    </p>
    
    
<p>
        By doing this we keep compatibility with registrations of the old
        actions (they just do not delegate by default) and also ensure that
        all new actions are by default delegating ones. Also a way to 
        suply a default implementation is there thus combining the flexibility
        of each 
        <a href="@org-openide-windows@/org/openide/windows/TopComponent.html" shape="rect">TopComponent</a>
        providing own implementation with the comfort of providing a default
        action suffient for common components.
    </p>
    
    
    
    
    
<h4>Always Enabled Action</h4>
    
<p>
        One can create a context-less, always enabled action. Of course,
        one can use <a href="@JDK@/javax/swing/AbstractAction.html" shape="rect">javax.swing.AbstractAction</a>
        to do that, however the support provided by this module allows one
        important addition - the action can be registered and displayed
        without loading any of the classes into memory. This is helpful
        for actions like <q>Open File</q>, <q>Open Project</q>, most of actions
        in <q>Window</q> submenu that opens singleton components and etc.
    </p>
    
    
<p>
        To register such action in a layer file use following syntax:
    </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.spi.actions.Factory.delegate" /&gt;
    &lt;attr name="delegate" newvalue="your.module.Listener" &gt;
    &lt;attr name="defaultCreate" boolvalue="true" &gt;
  &lt;/file&gt;
</pre>
    
<p>
        And write a class <code>your.module.Listener</code> that extends
        <code>javax.swing.ActionListener</code> and implements its 
        <code>actionPeformed</code> method. 
    </p>
    
    
<p>
        Such action is going to be always enabled and when invoked the registered
        listener is going to be instantiated and its method called. The localized
        name and icon of the action is going to be taken from the localized
        name and icon for the file using the standard I18N mechanism for
        layers - e.g. <code>SystemFileSystem.localizingBundle</code>, 
        <code>SystemFileSystem.icon</code>, <code>SystemFileSystem.icon32</code>
        attributes. <a href="#property-SystemFileSystem.icon24">SystemFileSystem.icon24</a>
            - As actions need also 24x24 color icon, there is additional
        support for specifying it. Just use 
        &lt;attr name="SystemFileSystem.icon24" urlvalue="..." /&gt; in the
        layer to provide definition of 24x24 icon for the action.
        
    </p>
    
    
    
    
<h4>Callback Action</h4>
    
<p>
       If one needs a placeholder action - e.g. an action that has the 
       name, icon, shortcut, but does not have the actual implementation.
       One can just use the standard way for registering actions in the
       layer, just do not provide the <code>defaultCreate</code> attribute.
       The proper delegate is then going to be discovered in runtime. 
       It is provided by the actual selected element (usually 
       <a href="@org-openide-windows@/org/openide/windows/TopComponent.html" shape="rect">TopComponent</a>).
       Also the enabled/disabled state is governed by the selected element's
       advices.
    </p>
    
    
<p>
        There are two steps one needs to do to declare such action. First of
        all one needs to provide a key and register such action in a layer:
    </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.spi.actions.Factory.callback" /&gt;
    &lt;attr name="key" stringvalue="your.module.Key" &gt;
  &lt;/file&gt;
</pre>
    
<p>
        The localization and icon is taken from the regular layer attributes.
        The value of the <q>key</q> then becomes the API that others can
        use to provide implementation of the action. So as a step two, one
        writes its own implementation of plain <a href="@JDK@/javax/swing/Action.html" shape="rect">javax.swing.Action</a>
        and registers it into <q>the selected</q> 
        <a href="@JDK@/javax/swing/ActionMap.html" shape="rect">ActionMap</a> - the 
        selected action map usually is 
        <a href="@org-openide-windows@/org/openide/windows/TopComponent.html" shape="rect">TopComponent.getActionMap()</a>
        of the component one is writing the action for.
    </p>
    
    
<p>
        The <em>callback action</em> is then going to listen on the changes
        in selected elements and update it state according state of the action
        one wants to delegate to.
        <!-- btw. we could also delegate the name of the action! -->
    </p>
    
    
    
    
<h4>Context and Callback actions with Fallback</h4>
    
<p>
        There is a <q>FindAction situation</q>: the action is in fact
        callback one and for example output window and editor can register
        its own action delegate into their component
        <a href="@JDK@/javax/swing/ActionMap.html" shape="rect">ActionMap</a>. 
        Then all the operation are delegated to the provided delegate.
        However
        there is also a <q>default</q> implementation based on presence 
        of <a href="@org-openidex-util@/org/openidex/search/SearchInfo.html" shape="rect">SearchInfo</a>
        interface in the context. Project, Files, Favorites views shall
        just place an instances of 
        <a href="@org-openidex-util@/org/openidex/search/SearchInfo.html" shape="rect">SearchInfo</a>
        into their context (usually into context of some of their nodes)
        and then the default impl shall extract all the needed info from there
        and act accordigly. Btw.
        <em>In the old system this does not work. The provider of the default
        implementation listen of set of components and if it likes them, it
        adds its delegate into their <a href="@JDK@/javax/swing/ActionMap.html" shape="rect">ActionMap</a>.
        Ugly, is it not?</em> 
    
</p>
    
    
<p>
        The solution to this problem could be in allowing a <q>default</q>
        fallback action to be specified for any <em>callback</em>. So there
        would be a factory method that would not only took a key to find
        the right delegate in the map, but also a implementation of an
        action to fallback to. In the declarative layer definition 
        it would be expressed as:
    </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.spi.actions.Factory.callback" /&gt;
    &lt;attr name="key" stringvalue="your.module.Key" &gt;
    &lt;attr name="defaultCreate" newvalue="your.module.prefix.FallbackAction" &gt;
  &lt;/file&gt;
</pre>
    
<p>
        The fallback instance would then be instantiated in a lazy fashion, 
        only if needed - e.g. if no delegate could be found in active context.
    </p>
    
    
    
    
<h4>Support for Long Running Actions</h4>
    
<p>
        All actions are by default executed on AWT event thread. Also their
        enablement state is guaranteed to be computed on AWT thread as well.
        
    </p>    
    
<p>
        If an enablement state should take longer to compute, then it is 
        adviced to keep the action always enabled and if it is invoked 
        in an inapropriate situation then just do nothing.
    </p>
    
    
<p>
        If an execution of the action's performer it taking long time, then
        it is adviced to move the execution to background. User shall be
        notified about running background tasks by the use of the
        <a href="#java-ProgressAPI">ProgressAPI</a>.
    </p>
    
    
<p>
        To support testing and UI scripting a contract to invoke background
        actions synchronously shall be followed. If the <code>actionPerformed</code>
        method is called with <a href="@JDK@/java.awt.event.ActionEvent" shape="rect">
            ActionEvent(somone, id, "waitFinished")
        </a> command <q>waitFinished</q> then the actionPerformed method
        should return after whole initialization is over.
    </p>
    
    
<p>
        There is a support to make writing the above described contracts
        simpler. A factory method that takes an interface with three methods:
    </p>
    
<pre xml:space="preserve">
    public interface AsynchronousWorker&lt;T&gt; {
        public ProgressHandle initialize();
        public T work(ProgressHandle);
        public void finish(ProgressHandle, T);
    }
    </pre>
    
<p>
        
<code>initialize</code> is called on AWT thread and returns a <code>ProgressHandle</code>,
        then <code>work</code> is called outside of the thread and gets handle as an argument.
        The <code>finish</code> is again called on AWT thread and gets handle as well
        as returned value from the background method. The action created
        by this factory method honors the <q>waitFinished</q> contract.
    </p>
    
    
    
<h4>Context Aware Actions</h4>
    
<p>
        To support situation where one module does have a piece of data and
        wants other module to create an unlimited range of actions that 
        works on such data, NetBeans provide a powerful mechanism of context
        aware actions.
    </p>
    
    
<p>
        A module who wishes to expose a piece of data creates an interface
        in its API to encapsulate them and makes sure the interface get's exposed 
        in <a href="@org-openide-util@/org/openide/util/Utilities.html#actionsGlobalContext()" shape="rect">
        Utilities.actionGlobalContext()
        </a>. This can be done by putting the interface into 
        <a href="@org-openide-windows@/org/openide/windows/TopComponent.html#getLookup()" shape="rect">lookup</a>
        of module's top components or 
        <a href="@org-openide-nodes@/org/openide/nodes/Node.html#getLookup()" shape="rect">lookup of its Nodes</a>.
    </p>
    
    
<p>
        The other modules then just use the <code>context</code> factory method
        with provided <code>Class&lt;DataType&gt;</code> of the API interface that encapsulates
        the data and provide subclass of <code>ContextActionPerformer&lt;DataType&gt;</code> 
        that provides implementation of 
        <code>actionPerformed(ActionEvent ev, DataType[] arr)</code>
        handling the execution of the action on given instances of DataType.
    </p>
    
    
<p>
        By using just the <code>ContextActionPerformer</code> one creates action
        that is always enabled if given <code>DataType</code> is present in the
        active context, that however may not be enough for all situations.
        For example project actions needs to extract the project from a
        file/data object and then decide. For them there is a way to also supply
        <code>ContextActionController&lt;DataType&gt;</code> that has method 
        <code>enabled(DataType[] types)</code> to compute the enabled state
        programmatically and control both the enablement and well as execution.
    </p>
 
    
<p>
        Context aware actions can be registered in a layer of module to prevent 
        the actual <code>ContextActionPerformer</code> to be instantiated until
        really needed:
    </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.spi.actions.Factory.context" /&gt;
    &lt;attr name="key" stringvalue="your.module.key.for.those.who.want.to.provide.their.own.impl" /&gt;
    &lt;attr name="defaultCreate" boolvalue="true" /&gt;
    &lt;attr name="type" stringvalue="your.module.DataType" &gt;
    &lt;attr name="actionPerformer" newvalue="your.module.ContextActionPerformerImpl" &gt;
  &lt;/file&gt;
</pre>
    
<p>
        As usually, display name and icon are taken by the standard attributes
        provided by SystemFileSystem.
    </p>
    
    
    
    
<h4>Adjusting Display Name to Context</h4>
    
<p>
        In some situations the display name of the action in menu or popup menu
        should change according the actual selection. This is supported for 
        those actions where it makes sence - the callback and context actions.
    </p>    
    
    
<p>
        When creating a callback action one can specify that the name shall
        be taken from the actual delegate. As a result either default name is
        used when there is noone to delegate to, or the name of the delegate is
        shown in menu and popup menu.
    </p>
    
    
<p>
        If one wishes to influence the display name of an context action, one needs to
        write additional interface <code>ContextActionName</code> that's only
        method takes an array of <code>DataType</code> and returns string to
        be used for display name. It is possible to return different 
        name for popup menu and for top menu.
    </p>
    
    
<p>
        Another problem related to display name is that currently actions'
        display name can always be influenced by associated context. This 
        can cause problems to infrastructure like Tools/Options dialog where
        actions have name of lastly selected node. This is solved by
        using <code>Lookup.EMPTY</code> by default as the context for the 
        newly created actions. Menus, Toolbars, will then explicitly bind
        these actions to <code>Utilities.actionsGlobalContext()</code> which
        is the context representing the main window.
    </p>
    
    

    
    
<h4>Context Actions Working on Enhanced Lookup</h4>
    
<p>
        In some situations an action may need to work on a different lookup
        content then one provided. For example an action may need <code>Project</code>
        interface in its context, but the original context just contains
        a <code>FileObject</code>. 
    </p>    
    
    
<p>
        To achieve this one needs to write a <em>lookup to lookup</em>
        convertor and use a factory methods that converts one 
        <a href="@org-openide-util@/org/openide/util/ContextAwareAction.html" shape="rect">
            ContextAwareAction
        </a> to another. The framework then takes care of caching and 
        the created lookup and always passing the old action the lookup
        transfered by the convertor. 
    </p>
    
<p>
        That way the convertor can always check the content of the old
        context for <code>FileObject</code> and based on using some 
        magic query create a wrapper lookup adding also an instance of
        <code>Project</code> there.
    </p>
    
    
    
    
<h4>Marking Default Action In Bold</h4>
        <!-- #9679 -->
        
<p>
            This is really old issue (#9679) and it is still open as it 
            seemed unsolvable till now. However recently it has been found
            that there is a way for the action to found out if it is the
            default action or not, if it uses the <code>Node.getPreferredAction()</code>
            method. If the context the actions works in contains just one
            node and someone is building a popup menu for it, then the one
            action returned from <code>Node.getPreferredAction()</code> can
            draw itself in bold. So this can work for 
            <a href="@org-openide-nodes@/org/openide/util/actions/NodeAction.html" shape="rect">NodeAction</a>
            and
            <a href="@org-openide-nodes@/org/openide/util/actions/CookieAction.html" shape="rect">CookieAction</a>
            for the other we need some kind of <q>node awarence</q>.
        </p>
        
        
<p>
            Anyway the <em>default action</em> often depends on the view
            that invokes the action, so the infrastructure just provides
            new factory method <code>Utilities.actionsToPopup(actions, context, defaultAction)</code>
            and the views will be allowed to extract the default action
            from their elements and use it:
        </p>
<pre xml:space="preserve">
Node[] arr = ...;                
Action def = (arr.length == 1) ? arr[0].getPreferredAction() : null;
createPopup(xpos, ypos, Utilities.actionsToPopup(actions, this, def));
</pre>

        
<p>
            The default action is then going to be communicated via a 
            property <a href="#property-defaultAction">defaultAction</a>
            - 
                that is going to be associated on the <a href="@JDK@/javax/swing/JMenuItem.html" shape="rect">JMenuItem</a>
                created as a presenter for the action.
            
        ~</p>
    
    
    
    
<h4>Handling Multi Selection</h4>
        
<p>
            Multiselection support is important for context actions. The other
            types do not need it. Always enabled are indeed always enabled and
            the callback actions just should not delegate to more than one
            delegate, that would unnecessary complicate things.
        </p>
        
        
<p>
            The easy and hopefully useful default behaviour for context actions
            shall be <q>some of them</q> mode: E.g. regarding of how many elements
            is selected, if at least one of them provides the desired context data,
            then the action is enabled, and if invoked, it will get access to
            all data that provided the context. To implement this one needs 
            just the notion of <code>DataType</code>, one does not need to care
            about the properties of the selection provider at all.
        </p>
        
        
<p>
            Anything else however gets more complicated. For example to support
            <q>just one</q> mode - where the action is enabled if one element
            is selected and provides the data - checking for present of one
            data interface is not enough. Doing that could lead to selection
            of multiple elements where just one of them would provide the correct
            data type in its context. So it is clear that the action framework
            needs to be somehow aware of the concept of <q>selected element</q>.
        </p>
        
        
<p>
            Shall the selected element be 
            <a href="@org-openide-nodes@/org/openide/nodes/Node.html" shape="rect">Node</a>?
            Well that is not good idea, as until now we managed to keep the
            actions API without a reference to Node and including such rich
            API like <a href="@org-openide-nodes@/overview-summary.html" shape="rect">nodes</a>
            would needlessly complicate the learning curve. Moreover not 
            all views are Node based - the CVS <q>before commit</q> table is
            likely implemented without node backend.
        </p>
        
        
<p>
            This seems to lead to a need for a new API between the actions and
            the views using the actions. Somehow they need to inform each other
            about the multiselection situation. The possible ways to do it
            include:
        </p>
        
        
<ul>
            <!-- preferred by Jesse -->
            
<li>use of <a href="@org-openide-util@/org/openide/util/Lookup.Provider.html" shape="rect">Lookup.Provider</a>
                as the element interface - not used that way until now, but 
                very likely would identify the element. No retrofitting would
                have to be done for 
                <a href="@org-openide-nodes@/org/openide/nodes/Node.html" shape="rect">Node</a>
                as it already implements that interface.
            </li>
            
<li>query like pattern - it would process the current context and
                returned information about the number of selected elements.
                Would be implemented in Nodes to work correctly with nodes.
            </li>
            
<li>special <q>element</q> interface - would identify one selected
                element, <a href="@org-openide-nodes@/org/openide/nodes/Node.html" shape="rect">Node</a>
                node would be retrofitted to implement it.
            </li>
            <!-- Jesse does not like this one:
            <li>
                Lookup based contract - could use the differences between
                <a href="@org-openide-util@/org/openide/util/Lookup.Result.html#allItems" >Result.allItems</a>
                and 
                <a href="@org-openide-util@/org/openide/util/Lookup.Result.html#allInstances" >Result.allInstances</a>
                to notify the multiselection. The number of returned items
                would reflect the number of selected elements, those that
                do not provide the data type would return null. Similar pattern
                is already used to communitate null vs. Node[0] from 
                <code>TopComponent.getActivatedNodes()</code>.
            </li>
            -->
        
</ul>
        
        
<p>
            Regardless of what solution is finally selected, there is a clear
            need for an API between the actions framework and the views which
            needs to be addressed.
        </p>
        
    
    
    
<h4>Actions Acting On Last Suitable Context</h4>
        
<p>
            Sometimes it is reasonable to let the action to work on previous
            selection even if current selection does not have such actions. For
            example one may want the <q>Compile One File</q> action to work
            on last selected file even if we are for example in output window
            evaluating the errors printed by the compiler. And vice versa, 
            the <q>jump to next error</q> action provided by output should 
            work even if one is already in editor.
        </p>
        
        
<p>
            To create such context and callback actions one needs to specify,
            during their creation that they <q>survive focus change</q>. Then
            the action will remain associated with the last context that is 
            sufficent to trigger it:
        </p>
        
        
<ul>
            
<li>the callback action will always delegate to the delegate found in
            the last <a href="@JDK@/javax/swing/ActionMap.html" shape="rect">ActionMap</a>
            that provided action for its key.
            </li>
            
            
<li>
            the context action will keep its state associated with data
            from previous context if the new one does not provide any 
            instance of the data interface.
            </li>
        
</ul>
        
        
<p>
            One can specify that newly created action shall survive focus change
            in layer as well. Just add attribute <q>surviveFocusChange</q>
            to specification of callback and context actions:
        </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.spi.actions.Factory.context" /&gt;
    &lt;attr name="surviveFocusChange" boolvalue="true" &gt;
  &lt;/file&gt;
</pre>
    
    
    
<h4>Support same shortcut for different actions in different contexts</h4>
        <!-- #21184  -->
        
<p>
            There are multiple levels of such support. If the modules that 
            provide the different actions somehow
            know about each other, they can agree on a key, define a global
            callback action based on that key and then, in different contexts
            (e.g. <a href="@JDK@/javax/swing/ActionMap.html" shape="rect">ActionMap</a>s)
            each module can register different action. 
            
            <a href="#property-ActionMapKeys">ActionMapKeys</a>
            - 
                certain keys has been published by the platform and modules can use
                them to register their own implementation in action maps of their 
                components:
                <ul>
                    
<li>
<code>"cloneWindow"</code> - an action to be executed when a top component is to be cloned</li>
                    
<li>
<code>"closeWindow"</code> - an action when a view is about to be closed</li>
                    
<li>
<code>DefaultEditorKit.copyAction</code> - copy action handler</li>
                    
<li>
<code>DefaultEditorKit.cutAction</code> - cut action handler</li>
                    
<li>
<code>"delete"</code> - delete action handler</li>
                    
<li>
<code>DefaultEditorKit.pasteAction</code> - paste action handler</li>
                    
<li>
<code>"jumpNext"</code> - when a next element shall be selected</li>
                    
<li>
<code>"jumpPrev"</code> - when a previous element shall be selected</li>
                
</ul>
            
            
            
<br>
            
            This style of <q>sharing</q> however requires that the modules
            know each other and also that the set of actions that shares the
            same key is defined at compile time. 
        </p>
        
        
<p>
            There is another level of configurability - completely different
            actions, not knowing about each other could share the same key
            if they are enabled in different contexts. For example, one module 
            defines component which has action <em>copy</em> and registers for
            it keystroke <em>Ctrl-C</em>. Another module defines different
            component which has action <em>commit</em> and assigns it a key
            <em>Alt-C</em>. Later however, the end user or someone assembling
            and branding own app over these modules, decide that the defaults
            are not ok and that there is a need to that in both components
            both the actions can be invoked with <em>Ctrl-C</em>. The current
            system with <em>context</em> and <em>callback</em> actions does
            not allow the end user or the assembler of the application to 
            do such kind of mappings.
            To implement this it
            would be needed to allow one keystroke to map to more actions. 
            The system could know that in the first module component, <em>Ctrl-C</em>
            maps to <em>copy</em> and in the second module component it maps
            to <em>commit</em>. There are two solutions how to achive this:
         </p>
         
         
<ul>
            
<li>Either each component could have its own InputMap - 
            this is possible, but a bit complicated
            especially with respect to multi keystroke shortcuts - as found out
            during the <a href="http://openide.netbeans.org/tutorial/reviews/opinions_64621.html" shape="rect">multikeys support review</a>
            there is a need to for all the keystroke mappings to always share 
            the common prefix. 
             </li>
            
<li>More actions could be bound to one key - 
            this would probably require a change in the format of registration
            in the <code>Shortcuts</code> and <code>Keymaps</code> folders, but
            generally it could work as outlined in 
            <a href="http://www.netbeans.org/issues/show_bug.cgi?id=15926" shape="rect">issue 15926</a>.
            The system would always picked up the one action that is currently
            enabled.
            </li>
         
</ul>
            
         
<p>
             Anyway it is not really clear that this feature is that desirable. 
             Maybe we can live without it and that is why it is not going to be 
             solved for 5.1.
             <!-- #19485 [TBD, jrechtacek] - Use InputMap for handling of global shorcuts -->
        </p>
    
    
    <!--
        First see the <a href="@TOP@/org/openide/actions/doc-files/api.html">API description</a>. Here is just
    a list of frequently asked or interesting questions slowly expanding as
    people ask them:
    
    <h3>Actions faq:</h3>
    
    <usecase id="context-action-shortcuts" name="How to define configurable Shortcut for Component based shortcut?" >
<em><b>Q:</b>
The usual Swing way of defining Actions for your component is to create an Action instance and put it into the Input and Action maps of your component.
However how to make this Action's shortcut configurable from the Tools/Keyboard Shortcuts dialog?</em>
<p>
In order for the action to show up in Keyboards Shortcut dialog you need the action defined in the 
layer file under "Actions" folder and have the shortcut defined there under "Keymaps/&lt;Profile Name&gt;" linking to your action.
</p>
<pre>
    &lt;folder name="Actions" &gt;
        &lt;folder name="Window"&gt;
            &lt;file name="org-netbeans-core-actions-PreviousViewCallbackAction.instance"/&gt;
        &lt;/folder&gt;
    &lt;/folder&gt;

    &lt;folder name="Keymaps"&gt;
        &lt;folder name="NetBeans"&gt;
            &lt;file name="S-A-Left.shadow"&gt;
                &lt;attr name="originalFile" stringvalue="Actions/Window/org-netbeans-core-actions-PreviousViewCallbackAction.instance"/&gt;
            &lt;/file&gt;
        &lt;/folder&gt;
    &lt;/folder&gt;
</pre>
<p>
The mentioned Action has to be a subclass of <code>org.openide.util.actions.CallbackSystemAction</code>. It does not necessarily has to 
perform the action, it's just a placeholder for linking the shortcut. You might want to override it's <code>getActionMapKey()</code> and give it a 
reasonable key.
</p>
<p>
The actual action that does the work in your component (preferably a simple Swing <code>javax.swing.Action</code>)
is to be put into your <code>TopComponent</code>'s <code>ActionMap</code>. The key for the <code>ActionMap</code> 
has to match the key defined in the global action's <code>getActionMapKey()</code> method.
</p>
<pre>
        getActionMap().put("PreviousViewAction", new MyPreviousTabAction());
</pre>
<p>
This way even actions from multiple <code>TopComponent</code>s with the same gesture (eg. "switch to next tab") can share the same configurable shortcut.
</p>
<p>
Note: Don't define your action's shortcut and don't put it into any of the <code>TopComponent</code>'s
<code>javax.swing.InputMap</code>. Otherwise the component would not pick up the changed shortcut from the
global context.
</p>

    </usecase>
    
    -->

<p></p>
<font color="gray"><b><a name="answer-arch-time">Question (arch-time)</a>:</b><em>
            What are the time estimates of the work?
            
        </em></font>
<p></p>
<b>Answer:</b>
    
<p>
    The main goal - e.g. no need to rely on 
    <a href="@org-openide-util@/org/openide/util/actions/SystemAction.html" shape="rect">
        SystemAction
    </a> - has to be achived in one release. Best in <b>promo-h</b>.
    The API is designed in extensible way and covered by tests, so 
    incremental evolution will be possible in every future release.
    </p>
 
<p></p>
<font color="gray"><b><a name="answer-arch-quality">Question (arch-quality)</a>:</b><em>
            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?
            
        </em></font>
<p></p>
<b>Answer:</b>
    
<p>
    Obviously there is a lot of unit tests for the behaviour of 
    actions created using API of this module. There are few indicators
    that are determining if the quality is good:
    </p>
    
<ul>
        
<li>the provided functionality is working as expected - e.g. test coverage is good enough and tests passes</li>
        
<li>the module is capable enough to replace 90% of usages of the historic APIs</li>
        
<li>ProjectUI API Actions (de facto pioneers of the new way of writing actions, just not general
        enough) can be migrated to new infrastructure</li>
        
<li>Declarative registrations lowers # of loaded classes and help startup time</li>
        
<li>API follows the modern (e.g. newer than JDK 1.2) Swing patterns and allows easy integration of existing Swing Actions</li>
        
<li>API support can change all its templates to this new API</li>
    
</ul>
 
<p></p>
<font color="gray"><b><a name="answer-arch-where">Question (arch-where)</a>:</b><em>
            Where one can find sources for your module?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
<p>
            The sources for the module are in <a href="http://www.netbeans.org" shape="rect">NetBeans</a>
            CVS in 
            <a href="http://www.netbeans.org/source/browse/openide/actions" shape="rect">openide/actions</a>
            directory.
        </p>
</p>
 
</ul>
    
<hr>
<h2>Project and platform dependencies</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-dep-nb">Question (dep-nb)</a>:</b><em>
            What other NetBeans projects and modules does this one depend on?
            
        </em></font>
<p></p>
<b>Answer:</b>
    <a href="#java-UtilitiesAPI">UtilitiesAPI</a> the only one API that is really required.
<p>Default answer to this question is:<!--If you do not want default answer to be generated you can use <defaultanswer generate='none' /> here--><br>
<p>
<p>
            These modules are required in project.xml file:
            <!--<li><api type='import' group='java' category='private' name='org.openide.util' url='@org-openide-util@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            </api>
</li>            
--><!--<li><api type='import' group='java' category='private' name='org.openide.nodes' url='@org-openide-nodes@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            
                Specification version 
                6.2
                is required.
            </api>
</li>            
--><!--<li><api type='import' group='java' category='private' name='org.openide.awt' url='@org-openide-awt@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            
                Specification version 
                6.5
                is required.
            </api>
</li>            
--><!--<li><api type='import' group='java' category='private' name='org.openide.options' url='@org-openide-options@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            
                Specification version 
                6.2
                is required.
            </api>
</li>            
--><!--<li><api type='import' group='java' category='private' name='org.openide.text' url='@org-openide-text@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            
                Specification version 
                6.2
                is required.
            </api>
</li>            
--><!--<li><api type='import' group='java' category='private' name='org.openide.explorer' url='@org-openide-explorer@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            
                Specification version 
                6.2
                is required.
            </api>
</li>            
--><!--<li><api type='import' group='java' category='private' name='org.openide.dialogs' url='@org-openide-dialogs@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            
                Specification version 
                6.2
                is required.
            </api>
</li>            
--><!--<li><api type='import' group='java' category='private' name='org.openide.windows' url='@org-openide-windows@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            
                Specification version 
                6.2
                is required.
            </api>
</li>            
--><ul>
<li>
<a href="#java-org.openide.util">org.openide.util</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                </li>
<li>
<a href="#java-org.openide.nodes">org.openide.nodes</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                </li>
<li>
<a href="#java-org.openide.awt">org.openide.awt</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.5
                    is required.
                </li>
<li>
<a href="#java-org.openide.options">org.openide.options</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                </li>
<li>
<a href="#java-org.openide.text">org.openide.text</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                </li>
<li>
<a href="#java-org.openide.explorer">org.openide.explorer</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                </li>
<li>
<a href="#java-org.openide.dialogs">org.openide.dialogs</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                </li>
<li>
<a href="#java-org.openide.windows">org.openide.windows</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                </li>
</ul>
</p>
</p>
</p>
<p></p>
<font color="gray"><b><a name="answer-dep-non-nb">Question (dep-non-nb)</a>:</b><em>
            What other projects outside NetBeans does this one depend on?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-dep-platform">Question (dep-platform)</a>:</b><em>
            On which platforms does your module run? Does it run in the same
            way on each?
            
        </em></font>
<p></p>
<b>Answer:</b>
100% pure Java. It should run anywhere.
<p></p>
<font color="gray"><b><a name="answer-dep-jre">Question (dep-jre)</a>:</b><em>
            Which version of JRE do you need (1.2, 1.3, 1.4, etc.)?
            
        </em></font>
<p></p>
<b>Answer:</b>
It uses JRE 1.3.
<p></p>
<font color="gray"><b><a name="answer-dep-jrejdk">Question (dep-jrejdk)</a>:</b><em>
            Do you require the JDK or is the JRE enough?
        </em></font>
<p></p>
<b>Answer:</b>
JRE is enough.
</ul>

    
<hr>
<h2>Deployment</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-deploy-jar">Question (deploy-jar)</a>:</b><em>
            Do you deploy just module JAR file(s) or other files as well?
            
        </em></font>
<p></p>
<b>Answer:</b>
    Possible. Of course.
<p></p>
<font color="gray"><b><a name="answer-deploy-nbm">Question (deploy-nbm)</a>:</b><em>
            Can you deploy an NBM via the Update Center?
            
        </em></font>
<p></p>
<b>Answer:</b>
Yes.
<p></p>
<font color="gray"><b><a name="answer-deploy-shared">Question (deploy-shared)</a>:</b><em>
            Do you need to be installed in the shared location only, or in the user directory only,
            or can your module be installed anywhere?
            
        </em></font>
<p></p>
<b>Answer:</b>
Most of the platform cluster depends on this library so it very likely should be 
in shared location.
<p></p>
<font color="gray"><b><a name="answer-deploy-packages">Question (deploy-packages)</a>:</b><em>
            Are packages of your module made inaccessible by not declaring them
            public?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
Sure.
<p></p>
<font color="gray"><b><a name="answer-deploy-dependencies">Question (deploy-dependencies)</a>:</b><em>
            What do other modules need to do to declare a dependency on this one?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for deploy-dependencies
  </p>
 
</ul>
    
    
<hr>
<h2>Compatibility with environment</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-compat-i18n">Question (compat-i18n)</a>:</b><em>
            Is your module correctly internationalized?
            
        </em></font>
<p></p>
<b>Answer:</b>
Yes.
<p></p>
<font color="gray"><b><a name="answer-compat-standards">Question (compat-standards)</a>:</b><em>
            Does the module implement or define any standards? Is the 
            implementation exact or does it deviate somehow?
        </em></font>
<p></p>
<b>Answer:</b>
Before the Actions was build on <code>org.openide.util.actions.SystemAction</code>, this
was recently changed that Actions supports <code>javax.swing.Action</code> which
is java API standard, and Actions will be improving towards this more and more.
<p></p>
<font color="gray"><b><a name="answer-compat-version">Question (compat-version)</a>:</b><em>
            Can your module coexist with earlier and future
            versions of itself? Can you correctly read all old settings? Will future
            versions be able to read your current settings? Can you read
            or politely ignore settings stored by a future version?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
Yes up to now it is supposed to be compatible with older versions.
</ul>
    
    
<hr>
<h2>Access to resources</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-resources-file">Question (resources-file)</a>:</b><em>
            Does your module use <code>java.io.File</code> directly?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-resources-layer">Question (resources-layer)</a>:</b><em>
            Does your module provide own layer? Does it create any files or
            folders in it? What it is trying to communicate by that and with which 
            components?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
No in fact. Just concrete action implementation provided by this module
are typically used in xml layers.
<p></p>
<font color="gray"><b><a name="answer-resources-read">Question (resources-read)</a>:</b><em>
            Does your module read any resources from layers? For what purpose?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
There are special folders containing actions in xml layers.
<ul>

<li>
<em>Menu</em> contains actions which are present in menu.</li>

<li>
<em>Toolbars</em> contains actions which will be present in toolbars.</li>

<li>
<em>Shortcuts</em> contains actions which will have assigned shortcuts.</li>

<li>
<em>Actions</em> contains actions which are possible to manipulate with (via Options).</li>

</ul>

<em>Note:</em> Those layers are not necessarily read by Actions module. Probably 
it belongs to <em>Window system module</em>.
<p></p>
<font color="gray"><b><a name="answer-resources-mask">Question (resources-mask)</a>:</b><em>
            Does your module mask/hide/override any resources provided by other modules in
            their layers?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
</ul>

    
    
<hr>
<h2>Lookup of components</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-lookup-lookup">Question (lookup-lookup)</a>:</b><em>
            Does your module use <code>org.openide.util.Lookup</code>
            or any similar technology to find any components to communicate with? Which ones?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for lookup-lookup
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-lookup-register">Question (lookup-register)</a>:</b><em>
            Do you register anything into lookup for other code to find?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for lookup-register
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-lookup-remove">Question (lookup-remove)</a>:</b><em>
            Do you remove entries of other modules from lookup?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for lookup-remove
  </p>
 
</ul>

    
    <!-- classification of interfaces -->
    
    <!-- package names -->
    
    
    
<hr>
<h2>Execution Environment</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-exec-property">Question (exec-property)</a>:</b><em>
            Is execution of your code influenced by any environment or
            Java system (<code>System.getProperty</code>) property?
            
            
        </em></font>
<p></p>
<b>Answer:</b>


<p></p>
<font color="gray"><b><a name="answer-exec-component">Question (exec-component)</a>:</b><em>
            Is execution of your code influenced by any (string) property
            of any of your components?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
    
    <!-- JST-PENDING
There are used three values (via <code>Action.getValue()</code>).
<ul>
    <li><api name="OpenIDE-Transmodal-Action" group="property" category="devel" type="export">Inidicates action can be performed
    (typicaly via shortcut) even when dialog is popped out (modal or modeless).</api></li>
    <li><api name="delegates" group="property" category="devel" type="export">Used internaly in <code>PasteAction</code> delegate action
    which serves to pass an array of <code>PasteType</code> or <code>Action</code> to global instance (it is the only one
    which actually performs paste operation).</api></li>
    <li><api name="iconBase" group="property" category="devel" type="export">Used in companion to Actions.SMALL_ICON. Because there
    is no way to specify values for other types of icons the value of "iconBase" is used
    to construct the resource names of disabled, pressed and rollover icons. The value is
    expected to contain a resource path of the normal icon. Strings "_pressed",
    "_disabled" and "_rollover" are inserted before the suffix when searching for
    the other types of icons.</api></li>
    <li><api name="noIconInMenu" group="property" category="devel" type="export"> 
    Allowed value <code>Boolean.TRUE</code>.
    Influences the display of the action in the main menu, the item will have no icon there. Works for Actions that don't define custom MenuPresenter.
    </api></li>    
    <li><api name="PreferredIconSize" group="property" category="devel" type="export">
    Used to support 24x24 icons in toolbars. If toolbar button has client property "PreferredIconSize"
    set to Integer(24) button tries to load icon with name "iconBase" + "24" eg. "cut24.gif".
    Strings "_pressed","_disabled" and "_rollover" are inserted before the suffix when searching for
    the other types of icons eg.:"cut24_pressed.gif".</api></li>
    <li>
        <api name="waitFinished" group="property" category="friend" type="export">
             There is a new contract established between the caller of an action that
             allows mutual communication and possible synchronous execution even for 
             actions that by default perform their operations asynchronously. If the
             action's <code>actionPeformed</code> method is passed <code>ActionEvent</code>
             with command <q>waitFinished</q> the action shall be executed synchronously.
             The code:
             <pre>
             action.actionPerformed (new ActionEvent (this, 0, "waitFinished"))
             </pre>
             shall be executed synchronously, even if the action by default runs asynchronously.
             All asynchronous actions are asked to obey this contract, <code>CallableSystemAction</code>
             does it by default. However this contract is defined as friend one 
             and may be abandoned in future.
        </api>
    </li>
    
    
</ul>

    -->
    
    
<p>
        A very important aspect for behaviour of runtime behaviour of actions is their 
        implementation of <a href="#java-ActionsEquality">ActionsEquality</a>
            - 
            It depends implementation of <code>Action.equals(Object)</code> and
            <code>Action.hashCode()</code> methods. The implementation influences 
            the behaviour
            of actions on multi selections - e.g. when a popup menu for more
            than one node is invoked, only actions available on all of them 
            (tested by <code>equals</code> method) are shown. Generally
            actions are equal if they are <em>created with the same factory method
            providing the same arguments and they are assigned to the 
            same <a href="@org-openide-util@/org/openide/util/Lookup.html" shape="rect">context</a>
            </em>.
        . 
        
        Yet another think that needs to be properly implement is the 
        sharing of the value for <a href="#property-AcceleratorKey">AcceleratorKey</a>
            - 
            the value of <code>Action.ACCELERATOR_KEY</code> needs to be shared
            between all instances that are created by the same factory, using
            the same arguments.
        
    </p>


<p></p>
<font color="gray"><b><a name="answer-exec-ant-tasks">Question (exec-ant-tasks)</a>:</b><em>
            Do you define or register any ant tasks that other can use?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   No ant tasks.
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-exec-classloader">Question (exec-classloader)</a>:</b><em>
            Does your code create its own class loader(s)?
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-exec-reflection">Question (exec-reflection)</a>:</b><em>
            Does your code use Java Reflection to execute other code?
            
        </em></font>
<p></p>
<b>Answer:</b>


<p></p>
<font color="gray"><b><a name="answer-exec-privateaccess">Question (exec-privateaccess)</a>:</b><em>
            Are you aware of any other parts of the system calling some of 
            your methods by reflection?
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-exec-process">Question (exec-process)</a>:</b><em>
            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?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   Not at all.
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-exec-introspection">Question (exec-introspection)</a>:</b><em>
            Does your module use any kind of runtime type information (<code>instanceof</code>,
            work with <code>java.lang.Class</code>, etc.)?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for exec-introspection
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-exec-threading">Question (exec-threading)</a>:</b><em>
            What threading models, if any, does your module adhere to?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   Most of the action manipulation shall happen only on AWT event thread. This
   is going to be enforced by asserts. The constructor can however be called
   outside of the AWT event thread to lower the load during the action
   creation and also certain attributes like icon and context less name 
   can also be got from other threads.
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-security-policy">Question (security-policy)</a>:</b><em>
            Does your functionality require modifications to the standard policy file?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for security-policy
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-security-grant">Question (security-grant)</a>:</b><em>
            Does your code grant additional rights to some other code?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for security-grant
  </p>
 
</ul>
    
    
<hr>
<h2>Format of files and protocols</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-format-types">Question (format-types)</a>:</b><em>
            Which protocols and file formats (if any) does your module read or write on disk,
            or transmit or receive over the network? Do you generate an ant build script?
            Can it be edited and modified? 
            
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for format-types
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-format-dnd">Question (format-dnd)</a>:</b><em>
            Which protocols (if any) does your code understand during Drag &amp; Drop?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for format-dnd
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-format-clipboard">Question (format-clipboard)</a>:</b><em>
            Which data flavors (if any) does your code read from or insert to
            the clipboard (by access to clipboard on means calling methods on <code>java.awt.datatransfer.Transferable</code>?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for format-clipboard
  </p>
 
</ul>

    
    
<hr>
<h2>Performance and Scalability</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-perf-startup">Question (perf-startup)</a>:</b><em>
            Does your module run any code on startup?
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-perf-exit">Question (perf-exit)</a>:</b><em>
            Does your module run any code on exit?
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-exit
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-perf-scale">Question (perf-scale)</a>:</b><em>
            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?
            
        </em></font>
<p></p>
<b>Answer:</b>
This should be irrelevant, as far as I know, Actions shouldn't use any collections
of data or something like that. One exception I know is global keymap implementation
which scales linear.
<p></p>
<font color="gray"><b><a name="answer-perf-limit">Question (perf-limit)</a>:</b><em>
            Are there any hard-coded or practical limits in the number or size of
            elements your code can handle?
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-limit
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-perf-mem">Question (perf-mem)</a>:</b><em>
            How much memory does your component consume? Estimate
            with a relation to the number of windows, etc.
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-mem
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-perf-wakeup">Question (perf-wakeup)</a>:</b><em>
            Does any piece of your code wake up periodically and do something
            even when the system is otherwise idle (no user interaction)?
        </em></font>
<p></p>
<b>Answer:</b>
No. At least I do not know about that.
<p></p>
<font color="gray"><b><a name="answer-perf-progress">Question (perf-progress)</a>:</b><em>
            Does your module execute any long-running tasks?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-perf-huge_dialogs">Question (perf-huge_dialogs)</a>:</b><em>
            Does your module contain any dialogs or wizards with a large number of
            GUI controls such as combo boxes, lists, trees, or text areas?
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-huge_dialogs
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-perf-menus">Question (perf-menus)</a>:</b><em>
            Does your module use dynamically updated context menus, or
            context-sensitive actions with complicated and slow enablement logic?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-menus
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-perf-spi">Question (perf-spi)</a>:</b><em>
            How the performance of the plugged in code will be enforced?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-spi
  </p>
 
</ul>
    
    
    <!-- security -->
    <!-- recovery -->
    

</api-questions>





 

 

 

 



  













<!-- Question: compat-i18n

     <question id="compat-i18n">
            Is your module correctly internationalized?
            <hint>
            Correct internationalization means that it obeys instuctions 
            at <a href="http://www.netbeans.org/devhome/docs/i18n/index.html">
            NetBeans I18N pages</a>.
            </hint>
        </question>
-->




<!-- Question: compat-standards

     <question id="compat-standards">
            Does the module implements or defines any standards? Is the 
            implementation exact or it deviates somehow?
        </question>
-->




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




<!-- Question: dep-jre

     <question id="dep-jre">
            Which version of JRE you need (1.2, 1.3, 1.4, etc.)?
            <hint>
            It is expected that if your module runs on 1.x that it will run 
            on 1.x+1 if no, state that please. Also describe here cases where
            you run different code on different versions of JRE and why.
            </hint>
        </question>
-->




<!-- Question: dep-jrejdk

     <question id="dep-jrejdk">
            Do you require JDK or is JRE enough?
        </question>
-->




<!-- Question: dep-nb

     <question id="dep-nb">
            What other NetBeans projects this one depends on?
            <hint>
            If you want, describe such projects as imported API using
            the <code>&lt;api name="identification" type="import or export" category="stable" url="where is the description" /&gt;</code>
            </hint>
        </question>
-->




<!-- 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
            (see <a href="http://libs.netbeans.org">libraries</a>) and
            it is prefered to use this approach when more modules may
            depend on such third-party library.
            </hint>
        </question>
-->




<!-- Question: dep-platform

     <question id="dep-platform">
            On which platforms your module run? Any? Does it run in the same
            way?
            <hint>
            If your module is using JNI or deals with special differences of
            OSes like filesystems, etc. please describe here what they are.
            </hint>
        </question>
-->




<!-- Question: deploy-jar

     <question id="deploy-jar">
            Do you deploy just module JAR file(s) or some other files?
            <hint>
            If your module consist just from one module JAR file, just confirm that.
            If it uses more than one JAR, describe where there are located, how
            they refer to each other. 
            If it consist of module JAR(s) and other files, please describe
            what is their purpose, why other files are necessary. Please 
            make sure that installation/deinstallation leaves the system 
            in state as it was before installation.
            </hint>
        </question>
-->



<!--
        <question id="deploy-dependencies" when="final">
            What do other modules need to do to declare a dependency on this one?
            <hint>
                Provide a sample of the actual lines you would add to a module manifest
                to declare a dependency, for example using OpenIDE-Module-Module-Dependencies
                or OpenIDE-Module-Requires. You may use the magic token @SPECIFICATION-VERSION@
                to represent the current specification version of the module.
            </hint>
        </question>
-->
 


<!-- Question: deploy-nbm

     <question id="deploy-nbm">
            Can you deploy NBM via AutoUpdate center?
            <hint>
            If not why?
            </hint>
        </question>
-->




<!-- 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
            whenever possible (<a href="http://www.netbeans.org/download/apis/org/openide/doc-files/upgrade.html#3.4-public-packages">
            public packages
            </a>). 
            </hint>
        </question>
-->




<!-- Question: deploy-shared

     <question id="deploy-shared">
            Do you need to be installed in shared location or only in user directory?
            <hint>
            Installation location shall not matter, if it does explain why.
            </hint>
        </question>
-->




<!-- Question: exec-classloader

     <question id="exec-classloader">
            Does your code uses own classloader?
            <hint>
            A bit unusual. Please explain why and what for.
            </hint>
        </question>
-->




<!-- Question: exec-component

     <question id="exec-component">
            Is execution of your code influenced by (string) property
            of any of your components?
            
            <hint>
            Often <code>JComponent.getClientProperty</code>, <code>Action.getValue</code>
            or <code>PropertyDescriptor.getValue</code>, etc. are used to influence
            a behaviour of some code. This of course forms an interface that should
            be documented. Also if one depends on some interface that an object
            implements (<code>component instanceof Runnable</code>) that forms an
            API as well.
            </hint>
        </question>
-->




<!-- Question: exec-privateaccess

     <question id="exec-privateaccess">
            Are you aware of any other part 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>
-->




<!-- Question: exec-property

     <question id="exec-property">
            Is execution of your code influenced by any environment of
            system (<code>System.getProperty</code>) property?
            
            <hint>
            If there is a property that can change the behaviour of your 
            code, somebody will likely use it. You should describe what it does 
            and the stability category of this API. You may use
            <PRE>
                &lt;property name="id" category="private" &gt;
                    description of the property, where it is used, what it influence, etc.
                &lt;/property&gt;            
            </PRE>
            </hint>
        </question>
-->




<!-- Question: exec-reflection

     <question id="exec-reflection">
            Does your code uses java.lang.reflect to execute some other code?
            <hint>
            This usually indicates a missing or unsufficient 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>
-->



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




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




<!-- Question: perf-startup

     <question id="perf-startup">
            Does your module executes anything on startup?
        </question>
-->




<!-- Question: perf-wakeup

     <question id="perf-wakeup">
            Is any piece of your code waking up periodically?
        </question>
-->




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




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




<!-- Question: resources-mask

     <question id="resources-mask">
            Does your module mask/hide/override any resource provided by another one in
            module layer? 
            
            <hint>
            If you mask a file provided by another module, you probably depend
            on that and do not want the other module to (for example) change
            the file's name. That module shall thus make that file available as an API
            of some stability category.
            </hint>
        </question>
-->




<!-- Question: resources-read

     <question id="resources-read">
            Does your module read any resources from layers? For what purpose?
            
            <hint>
            As this is some kind of intermodule dependency, it is a kind of API.
            Please describe it and clasify according to 
            <a href="http://openide.netbeans.org/tutorial/api-design.html#categories">
            common stability categories</a>.
            </hint>
        </question>
-->








 



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



 

 




<!--
        <question id="format-clipboard" when="impl">
            Which data flavors (if any) does your code read from or insert to
            the clipboard (by access to clipboard on means calling methods on <code>java.awt.datatransfer.Transferable</code>?
            
            <hint>
            Often Node's deal with clipboard by usage of <code>Node.clipboardCopy, Node.clipboardCut and Node.pasteTypes</code>.
            Check your code for overriding these methods.
            </hint>
        </question>
-->
 



<!--
        <question id="format-dnd" when="impl">
            Which protocols (if any) does your code understand during Drag &amp; Drop?
            <hint>
            Often Node's deal with clipboard by usage of <code>Node.drag, Node.getDropType</code>. 
            Check your code for overriding these methods. Btw. if they are not overridden, they
            by default delegate to <code>Node.clipboardCopy, Node.clipboardCut and Node.pasteTypes</code>.
            </hint>
        </question>
-->
 



<!--
        <question id="format-types" when="impl">
            Which protocols and file formats (if any) does your module read or write on disk,
            or transmit or receive over the network? Do you generate an ant build script?
            Can it be edited and modified? 
            
            <hint>
            <p>
            Files can be read and written by other programs, modules and users. If they influence
            your behaviour, make sure you either document the format or claim that it is a private
            api (using the &lt;api&gt; tag). 
            </p>
            
            <p>
            If you generate an ant build file, this is very likely going to be seen by end users and
            they will be attempted to edit it. You should be ready for that and provide here a link
            to documentation that you have for such purposes and also describe how you are going to
            understand such files during next release, when you (very likely) slightly change the 
            format.
            </p>
            </hint>
        </question>
-->
 



<!--
        <question id="lookup-lookup" when="init">
            Does your module use <code>org.openide.util.Lookup</code>
            or any similar technology to find any components to communicate with? Which ones?
            
            <hint>
            Please describe the interfaces you are searching for, where 
            are defined, whether you are searching for just one or more of them,
            if the order is important, etc. Also classify the stability of such
            API contract. For that use &lt;api group=&amp;lookup&amp; /&gt; tag.
            </hint>
        </question>
-->
 



<!--
        <question id="lookup-register" when="final">
            Do you register anything into lookup for other code to find?
            <hint>
            Do you register using layer file or using <code>META-INF/services</code>?
            Who is supposed to find your component?
            </hint>
        </question>
-->
 



<!--
        <question id="lookup-remove" when="final">
            Do you remove entries of other modules from lookup?
            <hint>
            Why? Of course, that is possible, but it can be dangerous. Is the module
            your are masking resource from aware of what you are doing?
            </hint>
        </question>
-->
 



<!--
        <question id="perf-exit" when="final">
            Does your module run any code on exit?
        </question>
-->
 



<!--
        <question id="perf-huge_dialogs" when="final">
            Does your module contain any dialogs or wizards with a large number of
            GUI controls such as combo boxes, lists, trees, or text areas?
        </question>
-->
 



<!--
        <question id="perf-limit" when="init">
            Are there any hard-coded or practical limits in the number or size of
            elements your code can handle?
        </question>
-->
 



<!--
        <question id="perf-mem" when="final">
            How much memory does your component consume? Estimate
            with a relation to the number of windows, etc.
        </question>
-->
 



<!--
        <question id="perf-menus" when="final">
            Does your module use dynamically updated context menus, or
            context-sensitive actions with complicated and slow enablement logic?
            <hint>
                If you do a lot of tricks when adding actions to regular or context menus, you can significantly
                slow down display of the menu, even when the user is not using your action. Pay attention to
                actions you add to the main menu bar, and to context menus of foreign nodes or components. If
                the action is conditionally enabled, or changes its display dynamically, you need to check the
                impact on performance. In some cases it may be more appropriate to make a simple action that is
                always enabled but does more detailed checks in a dialog if it is actually run.
            </hint>
        </question>
-->
 



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



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



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


</api-answers>
</body>
</html>

Attachment #28679
Version of arch document from Jan31, 2006, that includes all review comments	text/html	2006-01-31 16:19:14 UTC	94.69 KB	no flags	Details

<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Actions - NetBeans Architecture Questions</title>
</head>
<body>
<h1>NetBeans Architecture Answers for Actions module</h1>
<ul>
<li>
<b>Author:</b> jtulach@netbeans.org</li>
<li>
<b>Answers as of:</b> 31.1.2006</li>
<li>
<b>Answers for questions version:</b> 1.26</li>
<li>
<b>Latest available version of questions:</b> 1.27</li>
</ul>
<strong>
                        WARNING: answering questions version 1.26
                        rather than the current 1.27.
                    </strong>
<hr>
<h2>Interfaces table</h2>
<a name="group-property">
<h5>Group of property interfaces</h5>
</a>
<table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%">
<tr>
<td>
<table border="0" cellpadding="3" cellspacing="1" width="100%">
<tr class="tablersh">
<td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td>
</tr>
<tr class="tabler">
<td>SystemFileSystem.icon24</td><td>Exported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-stable">Stable</a></td><td><a name="property-SystemFileSystem.icon24">
<p></p>As actions need also 24x24 color icon, there is additional
        support for specifying it. Just use 
        &lt;attr name="SystemFileSystem.icon24" urlvalue="..." /&gt; in the
        layer to provide definition of 24x24 icon for the action.
        <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>defaultAction</td><td>Exported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-stable">Stable</a></td><td><a name="property-defaultAction">
<p></p>
                that is going to be associated on the <a href="@JDK@/javax/swing/JMenuItem.html" shape="rect">JMenuItem</a>
                created as a presenter for the action.
            <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>ActionMapKeys</td><td>Exported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-stable">Stable</a></td><td><a name="property-ActionMapKeys">
<p></p>
                certain keys has been published by the platform and modules can use
                them to register their own implementation in action maps of their 
                components:
                <ul>
                    
<li>
<code>"cloneWindow"</code> - an action to be executed when a top component is to be cloned</li>
                    
<li>
<code>"closeWindow"</code> - an action when a view is about to be closed</li>
                    
<li>
<code>DefaultEditorKit.copyAction</code> - copy action handler</li>
                    
<li>
<code>DefaultEditorKit.cutAction</code> - cut action handler</li>
                    
<li>
<code>"delete"</code> - delete action handler</li>
                    
<li>
<code>DefaultEditorKit.pasteAction</code> - paste action handler</li>
                    
<li>
<code>"jumpNext"</code> - when a next element shall be selected</li>
                    
<li>
<code>"jumpPrev"</code> - when a previous element shall be selected</li>
                
</ul>
            
<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>AcceleratorKey</td><td>Exported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-stable">Stable</a></td><td><a name="property-AcceleratorKey">
<p></p>
            the value of <code>Action.ACCELERATOR_KEY</code> needs to be shared
            between all instances that are created by the same factory, using
            the same arguments.
        <p></p>
</a></td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<a name="group-javax.swing.UIManager">
<h5>Group of javax.swing.UIManager interfaces</h5>
</a>
<table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%">
<tr>
<td>
<table border="0" cellpadding="3" cellspacing="1" width="100%">
<tr class="tablersh">
<td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td>
</tr>
<tr class="tabler">
<td>org.netbeans.actions.DefaultAction</td><td>Exported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-devel">Under Development</a></td><td><a name="javax.swing.UIManager-org.netbeans.actions.DefaultAction">
<p></p>property that can influence whether or not mark the default action
            in bold.
            <p></p>
</a></td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<a name="group-java">
<h5>Group of java interfaces</h5>
</a>
<table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%">
<tr>
<td>
<table border="0" cellpadding="3" cellspacing="1" width="100%">
<tr class="tablersh">
<td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td>
</tr>
<tr class="tabler">
<td>UtilitiesAPI</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-official">Official</a></td><td><a name="java-UtilitiesAPI"><a href="@org-openide-util@/overview-summary.html">@org-openide-util@/overview-summary.html</a>
<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.util</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.util"><a href="@org-openide-util@/overview-summary.html">@org-openide-util@/overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.nodes</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.nodes"><a href="@org-openide-nodes@/overview-summary.html">
                            .../overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.awt</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.awt"><a href="@org-openide-awt@/overview-summary.html">@org-openide-awt@/overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.5
                    is required.
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.options</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.options"><a href="@org-openide-options@/overview-summary.html">
                            .../overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.text</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.text"><a href="@org-openide-text@/overview-summary.html">@org-openide-text@/overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.explorer</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.explorer"><a href="@org-openide-explorer@/overview-summary.html">
                            .../overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.dialogs</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.dialogs"><a href="@org-openide-dialogs@/overview-summary.html">
                            .../overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>org.openide.windows</td><td>Imported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">Private</a></td><td><a name="java-org.openide.windows"><a href="@org-openide-windows@/overview-summary.html">
                            .../overview-summary.html</a>
<p></p>
<p></p>
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                <p></p>
</a></td>
</tr>
<tr class="tabler">
<td>ActionsEquality</td><td>Exported</td><td><a href="http://openide.netbeans.org/tutorial/api-design.html#category-stable">Stable</a></td><td><a name="java-ActionsEquality">
<p></p>
            It depends implementation of <code>Action.equals(Object)</code> and
            <code>Action.hashCode()</code> methods. The implementation influences 
            the behaviour
            of actions on multi selections - e.g. when a popup menu for more
            than one node is invoked, only actions available on all of them 
            (tested by <code>equals</code> method) are shown. Generally
            actions are equal if they are <em>created with the same factory method
            providing the same arguments and they are assigned to the 
            same <a href="@org-openide-util@/org/openide/util/Lookup.html" shape="rect">context</a>
            </em>.
        <p></p>
</a></td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<!--
                Sun Public License Notice

The contents of this file are subject to the Sun Public License
Version 1.0 (the "License"). You may not use this file except in
compliance with the License. A copy of the License is available at
http://www.sun.com/

The Original Code is NetBeans. The Initial Developer of the Original
Code is Sun Microsystems, Inc. Portions Copyright 1997-2005 Sun
Microsystems, Inc. All Rights Reserved.
-->
<api-answers author="jtulach@netbeans.org" module="Actions" question-version="1.26">

  
<!--
                Sun Public License Notice

The contents of this file are subject to the Sun Public License
Version 1.0 (the "License"). You may not use this file except in
compliance with the License. A copy of the License is available at
http://www.sun.com/

The Original Code is NetBeans. The Initial Developer of the Original
Code is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
Microsystems, Inc. All Rights Reserved.
-->

<!--
    Author     : Jaroslav Tulach, Jesse Glick
    Description: Questions that should be answered in order to make better API

    No PUBLIC or SYSTEM IDs defined currently.
-->

<!--
                        *** ATTENTION EDITORS ***
Please increment the 'version' field of <api-questions> whenever you make a
semantic change: adding a new question or significantly changing the meaning of
an old one. Changing this field ensures that arch pages answering the old version
print a warning during Javadoc generation. If you only change hints or make small
edits in the text of a question, you need not change the version number.

An automated process runs openide/www/tutorial/build.xml#question periodically
and commits any changes to openide/www/tutorial/questions.html.
-->

<api-questions version="1.27" xml:base="file:/doma/jarda/netbeans-src/nbbuild/antsrc/org/netbeans/nbbuild/Arch-api-questions.xml">
    
<hr>
<h2>General Information</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-arch-what">Question (arch-what)</a>:</b><em>
            What is this project good for?
            
        </em></font>
<p></p>
<b>Answer:</b>
    
<p>
    This module provides support for creation of actions, supports and
    takes care of their presentation in global menus, toolbars and popup 
    menu. By using methods and other APIs from this module one shall be
    able to easily create instances of <a href="@JDK@/javax/swing/Action.html" shape="rect">javax.swing.Action</a>
    which are ready to use in the NetBeans platform.
    </p>

<p></p>
<font color="gray"><b><a name="answer-arch-overall">Question (arch-overall)</a>:</b><em>
            Describe the overall architecture. 
            
        </em></font>
<p></p>
<b>Answer:</b>
    
<p>
    The architecture of this module builds on existing NetBeans Platform
    abstractions that has been proven to be useful. 
    This lowers the amount of changes in comparition
    from NetBeans 5.0 and concentrates them into relatively small, isolated
    area. The basic building block is 
    <a href="@org-openide-util@/org/openide/util/Utilities.html#actionsGlobalContext()" shape="rect">
        Utilities.actionGlobalContext()
    </a> and 
    <a href="@org-openide-util@/org/openide/util/ContextAwareAction.html" shape="rect">
        ContextAwareAction
    </a> interface. These were introduced to solve focus problems when 
    creating pop up menus on window managers with other then click-to-focus
    behaviours and seem to work quite well.
    </p>
    
    
<p>
    One of the most important goals is to remove the need to work with
    historic <a href="@org-openide-util@/org/openide/util/actions/SystemAction.html" shape="rect">
        SystemAction
    </a> and subclasses. Beyond the fact the they are instances of
    <a href="@org-openide-util@/org/openide/util/SharedClassObject.html" shape="rect">
        SharedClassObject
    </a> and such they have limited, complex and not very useful lifecycle
    management, they also rely on old and currently already obsolete concepts
    like <a href="@org-openide-nodes@/org/openide/nodes/Node.Cookie.html" shape="rect">Node.Cookie</a>.
    By using this module one does not need to care about the 
    <a href="@org-openide-util@/org/openide/util/actions/SystemAction.html" shape="rect">
        SystemAction
    </a> at all. A knowledge and understanding of 
    <a href="@org-openide-nodes@/org/openide/nodes/Node.Cookie.html" shape="rect">Node.Cookie</a>
    is required no more as well.
    </p>
    
    
<h5>Out Of Scope</h5>
    
    
<p>
        Part of overall description is also list of things that are not addressed
        by the effort. So it is wise to state that the actions module does not 
        addresses following issues:
    </p>
    
    
<ul>
        
<li>Do not change the concept of layers and system file system. 
            E.g. no namings, registries, etc. 
            Build on what is available right now.
        </li>
    
</ul>
 
<p></p>
<font color="gray"><b><a name="answer-arch-usecases">Question (arch-usecases)</a>:</b><em>
            
        
            Describe the main <a href="http://openide.netbeans.org/tutorial/api-design.html#usecase" shape="rect">
            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?
        </em></font>
<p></p>
<b>Answer:</b>
    
<h4>Defining An Action Placeholder</h4>
    
<p>
        The new design of actions framework is following the Swing JDK 1.3
        design as close as possible. That is why it is going to follow the
        <a href="@JDK@/javax.swing.InputMap" shape="rect">InputMap</a> and
        <a href="@JDK@/javax.swing.ActionMap" shape="rect">ActionMap</a> separation.
    </p>    
    
<p>
        The base constraint for this is to separate definition of action
        <em>key</em> from the actual definition of an action. The 
        key is then going to be put into a global 
        <a href="@JDK@/javax.swing.InputMap" shape="rect">InputMap</a>
        and assigned to a <a href="@JDK@/javax.swing.KeyStroke" shape="rect">KeyStroke</a>,
        while the actual action to be invoked is then put into an active
        <a href="@JDK@/javax.swing.ActionMap" shape="rect">ActionMap</a> and assigned
        to the specified key.
    </p>
    
    
<p>
        To achieve such state and also handle backward compatibility with older actions
        definition, all actions created by this module support the notion
        of a key and communicate with the whole system on registration 
        of the key and default action implementation into global
        <a href="@JDK@/javax.swing.InputMap" shape="rect">InputMap</a> and
        <a href="@JDK@/javax.swing.ActionMap" shape="rect">ActionMap</a>.
    </p>
    
    
<p>
        The basic pattern is based on layer definition inside the <code>Actions/</code>
        folder and its subfolders in layer where one can creates an action
        instance using one of the factories methods and assigns it a key:
    </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.spi.actions.Factory.oneOfFactoryMethods" /&gt;
    &lt;attr name="key" stringvalue="your.module.Key" &gt;
    &lt;attr name="defaultCreate" newvalue="your.module.prefix.YourAction" &gt;
  &lt;/file&gt;
</pre>
    
<p>
        The above snippet creates a registration of an action that can
        be then refered from <code>Menu</code>, <code>Toolbar</code>, <code>Shortcuts</code>
        folders and by default delegates to an active 
        <a href="@JDK@/javax.swing.ActionMap" shape="rect">ActionMap</a> to find out 
        the right action delegate to perform the operation - the value of the 
        <code>key</code> attribute is used to ask the 
        <a href="@JDK@/javax.swing.ActionMap" shape="rect">ActionMap</a> for the action delegate.
    </p>
    
    
<p>
        Beyond this <q>generic delegator</q> the usual action definition 
        also includes voluntary definition of a default implementation. E.g.
        some action that gets invoked if nobody provides a better implementation
        and registers it to the key into its own <a href="@JDK@/javax.swing.ActionMap" shape="rect">ActionMap</a>.
        Such default implementation is taken from a value of 
        <code>defaultCreate</code> attribute and can be instance of 
        existing class or <code>boolvalue="true"</code> to take
        the default provided by the <code>oneOfFactoryMethods</code>
        as discussed in next usecases. This default implementation
        is put into global <a href="@JDK@/javax.swing.ActionMap" shape="rect">ActionMap</a>
        which is by default parent map of any 
        <a href="@org-openide-windows@/org/openide/windows/TopComponent.html" shape="rect">TopComponent</a>.getActionMap()
        and as such serves as a fallback.
    </p>
    
    
<p>
        By doing this we keep compatibility with registrations of the old
        actions (they just do not delegate by default) and also ensure that
        all new actions are by default delegating ones. Also a way to 
        suply a default implementation is there thus combining the flexibility
        of each 
        <a href="@org-openide-windows@/org/openide/windows/TopComponent.html" shape="rect">TopComponent</a>
        providing own implementation with the comfort of providing a default
        action suffient for common components.
    </p>
    
    
    
    
    
<h4>Always Enabled Action</h4>
    
<p>
        One can create a context-less, always enabled action. Of course,
        one can use <a href="@JDK@/javax/swing/AbstractAction.html" shape="rect">javax.swing.AbstractAction</a>
        to do that, however the support provided by this module allows one
        important addition - the action can be registered and displayed
        without loading any of the classes into memory. This is helpful
        for actions like <q>Open File</q>, <q>Open Project</q>, most of actions
        in <q>Window</q> submenu that opens singleton components and etc.
    </p>
    
    
<p>
        To register such action in a layer file use following syntax:
    </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.spi.actions.Factory.delegate" /&gt;
    &lt;attr name="delegate" newvalue="your.module.Listener" &gt;
    &lt;attr name="defaultCreate" boolvalue="true" &gt;
  &lt;/file&gt;
</pre>
    
<p>
        And write a class <code>your.module.Listener</code> that extends
        <code>javax.swing.ActionListener</code> and implements its 
        <code>actionPeformed</code> method. 
    </p>
    
    
<p>
        Such action is going to be always enabled and when invoked the registered
        listener is going to be instantiated and its method called. The localized
        name and icon of the action is going to be taken from the localized
        name and icon for the file using the standard I18N mechanism for
        layers - e.g. <code>SystemFileSystem.localizingBundle</code>, 
        <code>SystemFileSystem.icon</code>, <code>SystemFileSystem.icon32</code>
        attributes. <a href="#property-SystemFileSystem.icon24">SystemFileSystem.icon24</a>
            - As actions need also 24x24 color icon, there is additional
        support for specifying it. Just use 
        &lt;attr name="SystemFileSystem.icon24" urlvalue="..." /&gt; in the
        layer to provide definition of 24x24 icon for the action.
        
    </p>
    
    
    
    
<h4>Callback Action</h4>
    
<p>
       If one needs a placeholder action - e.g. an action that has the 
       name, icon, shortcut, but does not have the actual implementation.
       One can just use the standard way for registering actions in the
       layer, just do not provide the <code>defaultCreate</code> attribute.
       The proper delegate is then going to be discovered in runtime. 
       It is provided by the actual selected element (usually 
       <a href="@org-openide-windows@/org/openide/windows/TopComponent.html" shape="rect">TopComponent</a>).
       Also the enabled/disabled state is governed by the selected element's
       advices.
    </p>
    
    
<p>
        There are two steps one needs to do to declare such action. First of
        all one needs to provide a key and register such action in a layer:
    </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.spi.actions.Factory.callback" /&gt;
    &lt;attr name="key" stringvalue="your.module.Key" &gt;
  &lt;/file&gt;
</pre>
    
<p>
        The localization and icon is taken from the regular layer attributes.
        The value of the <q>key</q> then becomes the API that others can
        use to provide implementation of the action. So as a step two, one
        writes its own implementation of plain <a href="@JDK@/javax/swing/Action.html" shape="rect">javax.swing.Action</a>
        and registers it into <q>the selected</q> 
        <a href="@JDK@/javax/swing/ActionMap.html" shape="rect">ActionMap</a> - the 
        selected action map usually is 
        <a href="@org-openide-windows@/org/openide/windows/TopComponent.html" shape="rect">TopComponent.getActionMap()</a>
        of the component one is writing the action for.
    </p>
    
    
<p>
        The <em>callback action</em> is then going to listen on the changes
        in selected elements and update it state according state of the action
        one wants to delegate to.
        <!-- btw. we could also delegate the name of the action! -->
    </p>
    
    
    
    
<h4>Context and Callback actions with Fallback</h4>
    
<p>
        There is a <q>FindAction situation</q>: the action is in fact
        callback one and for example output window and editor can register
        its own action delegate into their component
        <a href="@JDK@/javax/swing/ActionMap.html" shape="rect">ActionMap</a>. 
        Then all the operation are delegated to the provided delegate.
        However
        there is also a <q>default</q> implementation based on presence 
        of <a href="@org-openidex-util@/org/openidex/search/SearchInfo.html" shape="rect">SearchInfo</a>
        interface in the context. Project, Files, Favorites views shall
        just place an instances of 
        <a href="@org-openidex-util@/org/openidex/search/SearchInfo.html" shape="rect">SearchInfo</a>
        into their context (usually into context of some of their nodes)
        and then the default impl shall extract all the needed info from there
        and act accordigly. Btw.
        <em>In the old system this does not work. The provider of the default
        implementation listen of set of components and if it likes them, it
        adds its delegate into their <a href="@JDK@/javax/swing/ActionMap.html" shape="rect">ActionMap</a>.
        Ugly, is it not?</em> 
    
</p>
    
    
<p>
        The solution to this problem could be in allowing a <q>default</q>
        fallback action to be specified for any <em>callback</em>. So there
        would be a factory method that would not only took a key to find
        the right delegate in the map, but also a implementation of an
        action to fallback to. In the declarative layer definition 
        it would be expressed as:
    </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.spi.actions.Factory.callback" /&gt;
    &lt;attr name="key" stringvalue="your.module.Key" &gt;
    &lt;attr name="defaultCreate" newvalue="your.module.prefix.FallbackAction" &gt;
  &lt;/file&gt;
</pre>
    
<p>
        The fallback instance would then be instantiated in a lazy fashion, 
        only if needed - e.g. if no delegate could be found in active context.
    </p>
    
    
    
    
<h4>Context Aware Actions</h4>
    
<p>
        To support situation where one module does have a piece of data and
        wants other module to create an unlimited range of actions that 
        works on such data, NetBeans provide a powerful mechanism of context
        aware actions.
    </p>
    
    
<p>
        A module who wishes to expose a piece of data creates an interface
        in its API to encapsulate them and makes sure the interface get's exposed 
        in <a href="@org-openide-util@/org/openide/util/Utilities.html#actionsGlobalContext()" shape="rect">
        Utilities.actionGlobalContext()
        </a>. This can be done by putting the interface into 
        <a href="@org-openide-windows@/org/openide/windows/TopComponent.html#getLookup()" shape="rect">lookup</a>
        of module's top components or 
        <a href="@org-openide-nodes@/org/openide/nodes/Node.html#getLookup()" shape="rect">lookup of its Nodes</a>.
    </p>
    
    
<p>
        The other modules then just use the <code>context</code> factory method
        with provided <code>Class&lt;DataType&gt;</code> of the API interface that encapsulates
        the data and provide subclass of <code>ContextActionPerformer&lt;DataType&gt;</code> 
        that provides implementation of 
        <code>actionPerformed(ActionEvent ev, DataType[] arr)</code>
        handling the execution of the action on given instances of DataType.
    </p>
    
    
<p>
        By using just the <code>ContextActionPerformer</code> one creates action
        that is always enabled if given <code>DataType</code> is present in the
        active context, that however may not be enough for all situations.
        For example project actions needs to extract the project from a
        file/data object and then decide. For them there is a way to also supply
        <code>ContextActionController&lt;DataType&gt;</code> that has method 
        <code>enabled(DataType[] types)</code> to compute the enabled state
        programmatically and control both the enablement and well as execution.
    </p>
 
    
<p>
        Context aware actions can be registered in a layer of module to prevent 
        the actual <code>ContextActionPerformer</code> to be instantiated until
        really needed:
    </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.spi.actions.Factory.context" /&gt;
    &lt;attr name="key" stringvalue="your.module.key.for.those.who.want.to.provide.their.own.impl" /&gt;
    &lt;attr name="defaultCreate" boolvalue="true" /&gt;
    &lt;attr name="type" stringvalue="your.module.DataType" &gt;
    &lt;attr name="selectionType" stringvalue="exactlyOne" &gt;
    &lt;attr name="actionPerformer" newvalue="your.module.ContextActionPerformerImpl" &gt;
  &lt;/file&gt;
</pre>
    
<p>
        As usually, display name and icon are taken by the standard attributes
        provided by SystemFileSystem.
    </p>
    
    
    
    
<h4>Trigger Enablement Check</h4>
        Imagine an action working on applets only. 
        How to write it correctly to react to "extends Applet" addition/removal?        
    
    
    <h4>Adjusting Display Name to Context</h4>
    
<p>
        In some situations the display name of the action in menu or popup menu
        should change according the actual selection. This is supported for 
        those actions where it makes sence - the callback and context actions.
    </p>    
    
    
<p>
        When creating a callback action one can specify that the name shall
        be taken from the actual delegate. As a result either default name is
        used when there is noone to delegate to, or the name of the delegate is
        shown in menu and popup menu.
    </p>
    
    
<p>
        If one wishes to influence the display name of an context action, one needs to
        write additional interface <code>ContextActionName</code> that's only
        method takes an array of <code>DataType</code> and returns string to
        be used for display name. It is possible to return different 
        name for popup menu and for top menu.
    </p>
    
    
<p>
        Another problem related to display name is that currently actions'
        display name can always be influenced by associated context. This 
        can cause problems to infrastructure like Tools/Options dialog where
        actions have name of lastly selected node. This is solved by
        using <code>Lookup.EMPTY</code> by default as the context for the 
        newly created actions. Menus, Toolbars, will then explicitly bind
        these actions to <code>Utilities.actionsGlobalContext()</code> which
        is the context representing the main window.
    </p>
    
    

    
    
<h4>Marking Default Action In Bold</h4>
        <!-- #9679 -->
        
<p>
            This is really old issue (#9679) and it is still open as it 
            seemed unsolvable till now. However recently it has been found
            that there is a way for the action to found out if it is the
            default action or not, if it uses the <code>Node.getPreferredAction()</code>
            method. If the context the actions works in contains just one
            node and someone is building a popup menu for it, then the one
            action returned from <code>Node.getPreferredAction()</code> can
            draw itself in bold. So this can work for 
            <a href="@org-openide-nodes@/org/openide/util/actions/NodeAction.html" shape="rect">NodeAction</a>
            and
            <a href="@org-openide-nodes@/org/openide/util/actions/CookieAction.html" shape="rect">CookieAction</a>
            for the other we need some kind of <q>node awarence</q>.
        </p>
        
        
<p>
            Anyway the <em>default action</em> often depends on the view
            that invokes the action, so the infrastructure just provides
            new factory method <code>Utilities.actionsToPopup(actions, context, defaultAction)</code>
            and the views will be allowed to extract the default action
            from their elements and use it:
        </p>
<pre xml:space="preserve">
Node[] arr = ...;                
Action def = (arr.length == 1) ? arr[0].getPreferredAction() : null;
createPopup(xpos, ypos, Utilities.actionsToPopup(actions, this, def));
</pre>

        
<p>
            The default action is then going to be communicated via a 
            property <a href="#property-defaultAction">defaultAction</a>
            - 
                that is going to be associated on the <a href="@JDK@/javax/swing/JMenuItem.html" shape="rect">JMenuItem</a>
                created as a presenter for the action.
            
        </p>
        
        
<p>
            This problem is needs more UI work as the mnemonics behaviour
            is look and feel specific. That is why there needs to be 
            <a href="#javax.swing.UIManager-org.netbeans.actions.DefaultAction">org.netbeans.actions.DefaultAction</a>
            - property that can influence whether or not mark the default action
            in bold.
            
            <!-- it has also been discussed whether the first action shall 
            always be the default or not. But that does not work, as sometimes
            there is no default action (folder for example). Moreover our
            APIs allow the default action to be at different place than first,
            even it is on nice from UI perspective and is not going to be used
            that much, we need to be ready for such strange situation.
            -->
        </p>
    
    
    
    
<h4>Handling Multi Selection</h4>
        
<p>
            Multiselection support is important for context actions. The other
            types do not need it. Always enabled are indeed always enabled and
            the callback actions just should not delegate to more than one
            delegate, that would unnecessary complicate things.
        </p>
        
        
<p>
            The easy and hopefully useful default behaviour for context actions
            shall be <q>some of them</q> mode: E.g. regarding of how many elements
            is selected, if at least one of them provides the desired context data,
            then the action is enabled, and if invoked, it will get access to
            all data that provided the context. To implement this one needs 
            just the notion of <code>DataType</code>, one does not need to care
            about the properties of the selection provider at all.
        </p>
        
        
<p>
            Anything else however gets more complicated. For example to support
            <q>just one</q> mode - where the action is enabled if one element
            is selected and provides the data - checking for present of one
            data interface is not enough. Doing that could lead to selection
            of multiple elements where just one of them would provide the correct
            data type in its context. So it is clear that the action framework
            needs to be somehow aware of the concept of <q>selected element</q>.
        </p>
        
        
<p>
            Shall the selected element be 
            <a href="@org-openide-nodes@/org/openide/nodes/Node.html" shape="rect">Node</a>?
            Well that is not good idea, as until now we managed to keep the
            actions API without a reference to Node and including such rich
            API like <a href="@org-openide-nodes@/overview-summary.html" shape="rect">nodes</a>
            would needlessly complicate the learning curve. Moreover not 
            all views are Node based - the CVS <q>before commit</q> table is
            likely implemented without node backend.
        </p>
        
        
<p>
            This seems to lead to a need for a new API between the actions and
            the views using the actions. Somehow they need to inform each other
            about the multiselection situation. The possible ways to do it
            include:
        </p>
        
        
<ul>
            <!-- preferred by Jesse -->
            
<li>use of <a href="@org-openide-util@/org/openide/util/Lookup.Provider.html" shape="rect">Lookup.Provider</a>
                as the element interface - not used that way until now, but 
                very likely would identify the element. No retrofitting would
                have to be done for 
                <a href="@org-openide-nodes@/org/openide/nodes/Node.html" shape="rect">Node</a>
                as it already implements that interface.
            </li>
            
<li>query like pattern - it would process the current context and
                returned information about the number of selected elements.
                Would be implemented in Nodes to work correctly with nodes.
            </li>
            
<li>special <q>element</q> interface - would identify one selected
                element, <a href="@org-openide-nodes@/org/openide/nodes/Node.html" shape="rect">Node</a>
                node would be retrofitted to implement it.
            </li>
            <!-- Jesse does not like this one:
            <li>
                Lookup based contract - could use the differences between
                <a href="@org-openide-util@/org/openide/util/Lookup.Result.html#allItems" >Result.allItems</a>
                and 
                <a href="@org-openide-util@/org/openide/util/Lookup.Result.html#allInstances" >Result.allInstances</a>
                to notify the multiselection. The number of returned items
                would reflect the number of selected elements, those that
                do not provide the data type would return null. Similar pattern
                is already used to communitate null vs. Node[0] from 
                <code>TopComponent.getActivatedNodes()</code>.
            </li>
            -->
        
</ul>
        
        
<p>
            Regardless of what solution is finally selected, there is a clear
            need for an API between the actions framework and the views which
            needs to be addressed.
        </p>
        
    
    
    
<h4>Actions Acting On Last Suitable Context</h4>
        
<p>
            Sometimes it is reasonable to let the action to work on previous
            selection even if current selection does not have such actions. For
            example one may want the <q>Compile One File</q> action to work
            on last selected file even if we are for example in output window
            evaluating the errors printed by the compiler. And vice versa, 
            the <q>jump to next error</q> action provided by output should 
            work even if one is already in editor.
        </p>
        
        
<p>
            To create such context and callback actions one needs to specify,
            during their creation that they <q>survive focus change</q>. Then
            the action will remain associated with the last context that is 
            sufficent to trigger it:
        </p>
        
        
<ul>
            
<li>the callback action will always delegate to the delegate found in
            the last <a href="@JDK@/javax/swing/ActionMap.html" shape="rect">ActionMap</a>
            that provided action for its key.
            </li>
            
            
<li>
            the context action will keep its state associated with data
            from previous context if the new one does not provide any 
            instance of the data interface.
            </li>
        
</ul>
        
        
<p>
            One can specify that newly created action shall survive focus change
            in layer as well. Just add attribute <q>surviveFocusChange</q>
            to specification of callback and context actions:
        </p>

<pre xml:space="preserve">
  &lt;file name="your-module-prefix-YourActionId.instance" &gt;
    &lt;attr name="instanceCreate" methodvalue="org.netbeans.spi.actions.Factory.context" /&gt;
    &lt;attr name="surviveFocusChange" boolvalue="true" &gt;
  &lt;/file&gt;
</pre>
    
    
    
<h4>Conditionally Visible Action</h4>
        
<p>
            To write a context menu item which is conditionally visible 
            (not just enabled), one can use a factory method
            <code>createConditionallyVisibleMenuItem</code> that
            takes a factory method which, based on provided context
            returns an array of actions to make visible. Everything
            else is then handled by the infrastructure.
        </p>
        
        
<p>
            Another related problem is an action with own presenter. How
            that is going to be handled? A factory method that takes
            a lookup and returns JMenuItem or similar would solve the
            problem.
        </p>
    
    
    
<h4>Action Domains</h4>
        <!-- #21184  -->
        
<p>
            There are multiple levels of providing different reactions to
            the same shortcut or menu item. If the modules that 
            provide the different actions somehow
            know about each other, they can agree on a key, define a global
            callback action based on that key and then, in different contexts
            (e.g. <a href="@JDK@/javax/swing/ActionMap.html" shape="rect">ActionMap</a>s)
            each module can register different action. 
            
            <a href="#property-ActionMapKeys">ActionMapKeys</a>
            - 
                certain keys has been published by the platform and modules can use
                them to register their own implementation in action maps of their 
                components:
                <ul>
                    
<li>
<code>"cloneWindow"</code> - an action to be executed when a top component is to be cloned</li>
                    
<li>
<code>"closeWindow"</code> - an action when a view is about to be closed</li>
                    
<li>
<code>DefaultEditorKit.copyAction</code> - copy action handler</li>
                    
<li>
<code>DefaultEditorKit.cutAction</code> - cut action handler</li>
                    
<li>
<code>"delete"</code> - delete action handler</li>
                    
<li>
<code>DefaultEditorKit.pasteAction</code> - paste action handler</li>
                    
<li>
<code>"jumpNext"</code> - when a next element shall be selected</li>
                    
<li>
<code>"jumpPrev"</code> - when a previous element shall be selected</li>
                
</ul>
            
            
            
<br>
            
            This style of <q>sharing</q> however requires that the modules
            know each other and also that the set of actions that shares the
            same key is defined at compile time. 
        </p>
        
        
<p>
            There is another level of configurability - completely different
            actions, not knowing about each other could share the same key
            if they are enabled in different contexts. For example, one module 
            defines component which has action <em>copy</em> and registers for
            it keystroke <em>Ctrl-C</em>. Another module defines different
            component which has action <em>commit</em> and assigns it a key
            <em>Alt-C</em>. Later however, the end user or someone assembling
            and branding own app over these modules, decide that the defaults
            are not ok and that there is a need to that in both components
            both the actions can be invoked with <em>Ctrl-C</em>. The current
            system with <em>context</em> and <em>callback</em> actions does
            not allow the end user or the assembler of the application to 
            do such kind of mappings.
            To implement this it
            would be needed to allow one keystroke to map to more actions. 
            The system could know that in the first module component, <em>Ctrl-C</em>
            maps to <em>copy</em> and in the second module component it maps
            to <em>commit</em>. 
         </p>
         
         
<p>
            The solution is based on <q>action domains</q>. Any top component 
            can define its own domain - a place on system file system where
            its actions can be defined. Then its InputMap and also ActionMap 
            is going to be constructed from such folder in the same way as
            global input and action maps are constructed. By default
            they are going to delegate to the default map, but indeed, they
            can have its own actions and thus form an action domain. Care
            has to be taken with respect to to multi keystroke shortcuts - as found out
            during the <a href="http://openide.netbeans.org/tutorial/reviews/opinions_64621.html" shape="rect">multikeys support review</a>
            there is a need to for all the keystroke mappings to always share 
            the common prefix. Also if this is going to be used heavily,
            there needs to be a way to show these keys in options dialog.
         </p>
         <!-- #19485 [TBD, jrechtacek] - Use InputMap for handling of global shorcuts -->
    
    
    
<h4>Create Popup Menu</h4>
        
<p>
        I need to use user-configured shortcuts for private implementation 
        of well known actions (save, copy) and I need to create a 
        local popup menu for them. 
        </p>
        
        
<p>
        That is, I need to provide action mappings for keys like 
        "-openide-Save" and "-openide-Copy", have them bound to my 
        implementation in my context and have a simple way of creating 
        popup menu with my actions and all the usual 
        bells-and whistles (shortcuts automatically shown).        
        </p>
    
    
    
<h4>Dynamic Creation of Actions</h4>
        
<p>
        Imagine module similar to run a terminal emulator on nbextras.org but 
        more general that let users define links to applications presented 
        in some toolbar. User can add, remove and customize individual links. 
        Customization means: set icon, name, external program with parameters 
        and shortcut (similar to Desktop on your OS). It has a little sense 
        to code such a module if you couldn't pass as a parameter file 
        according to context. You need actually one action implemenetation 
        that could be parametrized and a way how to easily achieve 
        dynamic registration including all parameters and make this 
        registration permanent. 
        </p>
    
    
    <!--
        First see the <a href="@TOP@/org/openide/actions/doc-files/api.html">API description</a>. Here is just
    a list of frequently asked or interesting questions slowly expanding as
    people ask them:
    
    <h3>Actions faq:</h3>
    
    <usecase id="context-action-shortcuts" name="How to define configurable Shortcut for Component based shortcut?" >
<em><b>Q:</b>
The usual Swing way of defining Actions for your component is to create an Action instance and put it into the Input and Action maps of your component.
However how to make this Action's shortcut configurable from the Tools/Keyboard Shortcuts dialog?</em>
<p>
In order for the action to show up in Keyboards Shortcut dialog you need the action defined in the 
layer file under "Actions" folder and have the shortcut defined there under "Keymaps/&lt;Profile Name&gt;" linking to your action.
</p>
<pre>
    &lt;folder name="Actions" &gt;
        &lt;folder name="Window"&gt;
            &lt;file name="org-netbeans-core-actions-PreviousViewCallbackAction.instance"/&gt;
        &lt;/folder&gt;
    &lt;/folder&gt;

    &lt;folder name="Keymaps"&gt;
        &lt;folder name="NetBeans"&gt;
            &lt;file name="S-A-Left.shadow"&gt;
                &lt;attr name="originalFile" stringvalue="Actions/Window/org-netbeans-core-actions-PreviousViewCallbackAction.instance"/&gt;
            &lt;/file&gt;
        &lt;/folder&gt;
    &lt;/folder&gt;
</pre>
<p>
The mentioned Action has to be a subclass of <code>org.openide.util.actions.CallbackSystemAction</code>. It does not necessarily has to 
perform the action, it's just a placeholder for linking the shortcut. You might want to override it's <code>getActionMapKey()</code> and give it a 
reasonable key.
</p>
<p>
The actual action that does the work in your component (preferably a simple Swing <code>javax.swing.Action</code>)
is to be put into your <code>TopComponent</code>'s <code>ActionMap</code>. The key for the <code>ActionMap</code> 
has to match the key defined in the global action's <code>getActionMapKey()</code> method.
</p>
<pre>
        getActionMap().put("PreviousViewAction", new MyPreviousTabAction());
</pre>
<p>
This way even actions from multiple <code>TopComponent</code>s with the same gesture (eg. "switch to next tab") can share the same configurable shortcut.
</p>
<p>
Note: Don't define your action's shortcut and don't put it into any of the <code>TopComponent</code>'s
<code>javax.swing.InputMap</code>. Otherwise the component would not pick up the changed shortcut from the
global context.
</p>

    </usecase>
    
    -->

<p></p>
<font color="gray"><b><a name="answer-arch-time">Question (arch-time)</a>:</b><em>
            What are the time estimates of the work?
            
        </em></font>
<p></p>
<b>Answer:</b>
    
<p>
    The main goal - e.g. no need to rely on 
    <a href="@org-openide-util@/org/openide/util/actions/SystemAction.html" shape="rect">
        SystemAction
    </a> - has to be achived in one release. Best in <b>promo-h</b>.
    The API is designed in extensible way and covered by tests, so 
    incremental evolution will be possible in every future release.
    </p>
 
<p></p>
<font color="gray"><b><a name="answer-arch-quality">Question (arch-quality)</a>:</b><em>
            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?
            
        </em></font>
<p></p>
<b>Answer:</b>
    
<p>
    Obviously there is a lot of unit tests for the behaviour of 
    actions created using API of this module. There are few indicators
    that are determining if the quality is good:
    </p>
    
<ul>
        
<li>the provided functionality is working as expected - e.g. test coverage is good enough and tests passes</li>
        
<li>the module is capable enough to replace 90% of usages of the historic APIs</li>
        
<li>ProjectUI API Actions (de facto pioneers of the new way of writing actions, just not general
        enough) can be migrated to new infrastructure</li>
        
<li>Declarative registrations lowers # of loaded classes and help startup time</li>
        
<li>API follows the modern (e.g. newer than JDK 1.2) Swing patterns and allows easy integration of existing Swing Actions</li>
        
<li>API support can change all its templates to this new API</li>
    
</ul>
 
<p></p>
<font color="gray"><b><a name="answer-arch-where">Question (arch-where)</a>:</b><em>
            Where one can find sources for your module?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
<p>
            The sources for the module are in <a href="http://www.netbeans.org" shape="rect">NetBeans</a>
            CVS in 
            <a href="http://www.netbeans.org/source/browse/openide/actions" shape="rect">openide/actions</a>
            directory.
        </p>
</p>
 
</ul>
    
<hr>
<h2>Project and platform dependencies</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-dep-nb">Question (dep-nb)</a>:</b><em>
            What other NetBeans projects and modules does this one depend on?
            
        </em></font>
<p></p>
<b>Answer:</b>
    <a href="#java-UtilitiesAPI">UtilitiesAPI</a> the only one API that is really required.
<p>Default answer to this question is:<!--If you do not want default answer to be generated you can use <defaultanswer generate='none' /> here--><br>
<p>
<p>
            These modules are required in project.xml file:
            <!--<li><api type='import' group='java' category='private' name='org.openide.util' url='@org-openide-util@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            </api>
</li>            
--><!--<li><api type='import' group='java' category='private' name='org.openide.nodes' url='@org-openide-nodes@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            
                Specification version 
                6.2
                is required.
            </api>
</li>            
--><!--<li><api type='import' group='java' category='private' name='org.openide.awt' url='@org-openide-awt@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            
                Specification version 
                6.5
                is required.
            </api>
</li>            
--><!--<li><api type='import' group='java' category='private' name='org.openide.options' url='@org-openide-options@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            
                Specification version 
                6.2
                is required.
            </api>
</li>            
--><!--<li><api type='import' group='java' category='private' name='org.openide.text' url='@org-openide-text@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            
                Specification version 
                6.2
                is required.
            </api>
</li>            
--><!--<li><api type='import' group='java' category='private' name='org.openide.explorer' url='@org-openide-explorer@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            
                Specification version 
                6.2
                is required.
            </api>
</li>            
--><!--<li><api type='import' group='java' category='private' name='org.openide.dialogs' url='@org-openide-dialogs@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            
                Specification version 
                6.2
                is required.
            </api>
</li>            
--><!--<li><api type='import' group='java' category='private' name='org.openide.windows' url='@org-openide-windows@/overview-summary.html' >
            The module is needed for compilation. 
        
            The module is used during runtime. 
            
                Specification version 
                6.2
                is required.
            </api>
</li>            
--><ul>
<li>
<a href="#java-org.openide.util">org.openide.util</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                </li>
<li>
<a href="#java-org.openide.nodes">org.openide.nodes</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                </li>
<li>
<a href="#java-org.openide.awt">org.openide.awt</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.5
                    is required.
                </li>
<li>
<a href="#java-org.openide.options">org.openide.options</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                </li>
<li>
<a href="#java-org.openide.text">org.openide.text</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                </li>
<li>
<a href="#java-org.openide.explorer">org.openide.explorer</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                </li>
<li>
<a href="#java-org.openide.dialogs">org.openide.dialogs</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                </li>
<li>
<a href="#java-org.openide.windows">org.openide.windows</a>
            - 
                The module is needed for compilation. 
            
                The module is used during runtime. 
                
                    Specification version 
                    6.2
                    is required.
                </li>
</ul>
</p>
</p>
</p>
<p></p>
<font color="gray"><b><a name="answer-dep-non-nb">Question (dep-non-nb)</a>:</b><em>
            What other projects outside NetBeans does this one depend on?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-dep-platform">Question (dep-platform)</a>:</b><em>
            On which platforms does your module run? Does it run in the same
            way on each?
            
        </em></font>
<p></p>
<b>Answer:</b>
100% pure Java. It should run anywhere.
<p></p>
<font color="gray"><b><a name="answer-dep-jre">Question (dep-jre)</a>:</b><em>
            Which version of JRE do you need (1.2, 1.3, 1.4, etc.)?
            
        </em></font>
<p></p>
<b>Answer:</b>
It uses JRE 1.3.
<p></p>
<font color="gray"><b><a name="answer-dep-jrejdk">Question (dep-jrejdk)</a>:</b><em>
            Do you require the JDK or is the JRE enough?
        </em></font>
<p></p>
<b>Answer:</b>
JRE is enough.
</ul>

    
<hr>
<h2>Deployment</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-deploy-jar">Question (deploy-jar)</a>:</b><em>
            Do you deploy just module JAR file(s) or other files as well?
            
        </em></font>
<p></p>
<b>Answer:</b>
    Possible. Of course.
<p></p>
<font color="gray"><b><a name="answer-deploy-nbm">Question (deploy-nbm)</a>:</b><em>
            Can you deploy an NBM via the Update Center?
            
        </em></font>
<p></p>
<b>Answer:</b>
Yes.
<p></p>
<font color="gray"><b><a name="answer-deploy-shared">Question (deploy-shared)</a>:</b><em>
            Do you need to be installed in the shared location only, or in the user directory only,
            or can your module be installed anywhere?
            
        </em></font>
<p></p>
<b>Answer:</b>
Most of the platform cluster depends on this library so it very likely should be 
in shared location.
<p></p>
<font color="gray"><b><a name="answer-deploy-packages">Question (deploy-packages)</a>:</b><em>
            Are packages of your module made inaccessible by not declaring them
            public?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
Sure.
<p></p>
<font color="gray"><b><a name="answer-deploy-dependencies">Question (deploy-dependencies)</a>:</b><em>
            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)?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for deploy-dependencies
  </p>
 
</ul>
    
    
<hr>
<h2>Compatibility with environment</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-compat-i18n">Question (compat-i18n)</a>:</b><em>
            Is your module correctly internationalized?
            
        </em></font>
<p></p>
<b>Answer:</b>
Yes.
<p></p>
<font color="gray"><b><a name="answer-compat-standards">Question (compat-standards)</a>:</b><em>
            Does the module implement or define any standards? Is the 
            implementation exact or does it deviate somehow?
        </em></font>
<p></p>
<b>Answer:</b>
Before the Actions was build on <code>org.openide.util.actions.SystemAction</code>, this
was recently changed that Actions supports <code>javax.swing.Action</code> which
is java API standard, and Actions will be improving towards this more and more.
<p></p>
<font color="gray"><b><a name="answer-compat-version">Question (compat-version)</a>:</b><em>
            Can your module coexist with earlier and future
            versions of itself? Can you correctly read all old settings? Will future
            versions be able to read your current settings? Can you read
            or politely ignore settings stored by a future version?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
Yes up to now it is supposed to be compatible with older versions.
</ul>
    
    
<hr>
<h2>Access to resources</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-resources-file">Question (resources-file)</a>:</b><em>
            Does your module use <code>java.io.File</code> directly?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-resources-layer">Question (resources-layer)</a>:</b><em>
            Does your module provide own layer? Does it create any files or
            folders in it? What it is trying to communicate by that and with which 
            components?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
No in fact. Just concrete action implementation provided by this module
are typically used in xml layers.
<p></p>
<font color="gray"><b><a name="answer-resources-read">Question (resources-read)</a>:</b><em>
            Does your module read any resources from layers? For what purpose?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
There are special folders containing actions in xml layers.
<ul>

<li>
<em>Menu</em> contains actions which are present in menu.</li>

<li>
<em>Toolbars</em> contains actions which will be present in toolbars.</li>

<li>
<em>Shortcuts</em> contains actions which will have assigned shortcuts.</li>

<li>
<em>Actions</em> contains actions which are possible to manipulate with (via Options).</li>

</ul>

<em>Note:</em> Those layers are not necessarily read by Actions module. Probably 
it belongs to <em>Window system module</em>.
<p></p>
<font color="gray"><b><a name="answer-resources-mask">Question (resources-mask)</a>:</b><em>
            Does your module mask/hide/override any resources provided by other modules in
            their layers?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
</ul>

    
    
<hr>
<h2>Lookup of components</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-lookup-lookup">Question (lookup-lookup)</a>:</b><em>
            Does your module use <code>org.openide.util.Lookup</code>
            or any similar technology to find any components to communicate with? Which ones?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for lookup-lookup
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-lookup-register">Question (lookup-register)</a>:</b><em>
            Do you register anything into lookup for other code to find?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for lookup-register
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-lookup-remove">Question (lookup-remove)</a>:</b><em>
            Do you remove entries of other modules from lookup?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for lookup-remove
  </p>
 
</ul>

    
    <!-- classification of interfaces -->
    
    <!-- package names -->
    
    
    
<hr>
<h2>Execution Environment</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-exec-property">Question (exec-property)</a>:</b><em>
            Is execution of your code influenced by any environment or
            Java system (<code>System.getProperty</code>) property?
            
            
        </em></font>
<p></p>
<b>Answer:</b>


<p></p>
<font color="gray"><b><a name="answer-exec-component">Question (exec-component)</a>:</b><em>
            Is execution of your code influenced by any (string) property
            of any of your components?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
    
    <!-- JST-PENDING
There are used three values (via <code>Action.getValue()</code>).
<ul>
    <li><api name="OpenIDE-Transmodal-Action" group="property" category="devel" type="export">Inidicates action can be performed
    (typicaly via shortcut) even when dialog is popped out (modal or modeless).</api></li>
    <li><api name="delegates" group="property" category="devel" type="export">Used internaly in <code>PasteAction</code> delegate action
    which serves to pass an array of <code>PasteType</code> or <code>Action</code> to global instance (it is the only one
    which actually performs paste operation).</api></li>
    <li><api name="iconBase" group="property" category="devel" type="export">Used in companion to Actions.SMALL_ICON. Because there
    is no way to specify values for other types of icons the value of "iconBase" is used
    to construct the resource names of disabled, pressed and rollover icons. The value is
    expected to contain a resource path of the normal icon. Strings "_pressed",
    "_disabled" and "_rollover" are inserted before the suffix when searching for
    the other types of icons.</api></li>
    <li><api name="noIconInMenu" group="property" category="devel" type="export"> 
    Allowed value <code>Boolean.TRUE</code>.
    Influences the display of the action in the main menu, the item will have no icon there. Works for Actions that don't define custom MenuPresenter.
    </api></li>    
    <li><api name="PreferredIconSize" group="property" category="devel" type="export">
    Used to support 24x24 icons in toolbars. If toolbar button has client property "PreferredIconSize"
    set to Integer(24) button tries to load icon with name "iconBase" + "24" eg. "cut24.gif".
    Strings "_pressed","_disabled" and "_rollover" are inserted before the suffix when searching for
    the other types of icons eg.:"cut24_pressed.gif".</api></li>
    <li>
        <api name="waitFinished" group="property" category="friend" type="export">
             There is a new contract established between the caller of an action that
             allows mutual communication and possible synchronous execution even for 
             actions that by default perform their operations asynchronously. If the
             action's <code>actionPeformed</code> method is passed <code>ActionEvent</code>
             with command <q>waitFinished</q> the action shall be executed synchronously.
             The code:
             <pre>
             action.actionPerformed (new ActionEvent (this, 0, "waitFinished"))
             </pre>
             shall be executed synchronously, even if the action by default runs asynchronously.
             All asynchronous actions are asked to obey this contract, <code>CallableSystemAction</code>
             does it by default. However this contract is defined as friend one 
             and may be abandoned in future.
        </api>
    </li>
    
    
</ul>

    -->
    
    
<p>
        A very important aspect for behaviour of runtime behaviour of actions is their 
        implementation of <a href="#java-ActionsEquality">ActionsEquality</a>
            - 
            It depends implementation of <code>Action.equals(Object)</code> and
            <code>Action.hashCode()</code> methods. The implementation influences 
            the behaviour
            of actions on multi selections - e.g. when a popup menu for more
            than one node is invoked, only actions available on all of them 
            (tested by <code>equals</code> method) are shown. Generally
            actions are equal if they are <em>created with the same factory method
            providing the same arguments and they are assigned to the 
            same <a href="@org-openide-util@/org/openide/util/Lookup.html" shape="rect">context</a>
            </em>.
        . 
        
        Yet another think that needs to be properly implement is the 
        sharing of the value for <a href="#property-AcceleratorKey">AcceleratorKey</a>
            - 
            the value of <code>Action.ACCELERATOR_KEY</code> needs to be shared
            between all instances that are created by the same factory, using
            the same arguments.
        
    </p>


<p></p>
<font color="gray"><b><a name="answer-exec-ant-tasks">Question (exec-ant-tasks)</a>:</b><em>
            Do you define or register any ant tasks that other can use?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   No ant tasks.
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-exec-classloader">Question (exec-classloader)</a>:</b><em>
            Does your code create its own class loader(s)?
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-exec-reflection">Question (exec-reflection)</a>:</b><em>
            Does your code use Java Reflection to execute other code?
            
        </em></font>
<p></p>
<b>Answer:</b>


<p></p>
<font color="gray"><b><a name="answer-exec-privateaccess">Question (exec-privateaccess)</a>:</b><em>
            Are you aware of any other parts of the system calling some of 
            your methods by reflection?
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-exec-process">Question (exec-process)</a>:</b><em>
            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?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   Not at all.
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-exec-introspection">Question (exec-introspection)</a>:</b><em>
            Does your module use any kind of runtime type information (<code>instanceof</code>,
            work with <code>java.lang.Class</code>, etc.)?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for exec-introspection
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-exec-threading">Question (exec-threading)</a>:</b><em>
            What threading models, if any, does your module adhere to?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   Most of the action manipulation shall happen only on AWT event thread. This
   is going to be enforced by asserts. The constructor can however be called
   outside of the AWT event thread to lower the load during the action
   creation and also certain attributes like icon and context less name 
   can also be got from other threads.
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-security-policy">Question (security-policy)</a>:</b><em>
            Does your functionality require modifications to the standard policy file?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for security-policy
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-security-grant">Question (security-grant)</a>:</b><em>
            Does your code grant additional rights to some other code?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for security-grant
  </p>
 
</ul>
    
    
<hr>
<h2>Format of files and protocols</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-format-types">Question (format-types)</a>:</b><em>
            Which protocols and file formats (if any) does your module read or write on disk,
            or transmit or receive over the network? Do you generate an ant build script?
            Can it be edited and modified? 
            
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for format-types
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-format-dnd">Question (format-dnd)</a>:</b><em>
            Which protocols (if any) does your code understand during Drag &amp; Drop?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for format-dnd
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-format-clipboard">Question (format-clipboard)</a>:</b><em>
            Which data flavors (if any) does your code read from or insert to
            the clipboard (by access to clipboard on means calling methods on <code>java.awt.datatransfer.Transferable</code>?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for format-clipboard
  </p>
 
</ul>

    
    
<hr>
<h2>Performance and Scalability</h2>
<ul>
<p></p>
<font color="gray"><b><a name="answer-perf-startup">Question (perf-startup)</a>:</b><em>
            Does your module run any code on startup?
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-perf-exit">Question (perf-exit)</a>:</b><em>
            Does your module run any code on exit?
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-exit
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-perf-scale">Question (perf-scale)</a>:</b><em>
            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?
            
        </em></font>
<p></p>
<b>Answer:</b>
This should be irrelevant, as far as I know, Actions shouldn't use any collections
of data or something like that. One exception I know is global keymap implementation
which scales linear.
<p></p>
<font color="gray"><b><a name="answer-perf-limit">Question (perf-limit)</a>:</b><em>
            Are there any hard-coded or practical limits in the number or size of
            elements your code can handle?
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-limit
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-perf-mem">Question (perf-mem)</a>:</b><em>
            How much memory does your component consume? Estimate
            with a relation to the number of windows, etc.
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-mem
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-perf-wakeup">Question (perf-wakeup)</a>:</b><em>
            Does any piece of your code wake up periodically and do something
            even when the system is otherwise idle (no user interaction)?
        </em></font>
<p></p>
<b>Answer:</b>
No. At least I do not know about that.
<p></p>
<font color="gray"><b><a name="answer-perf-progress">Question (perf-progress)</a>:</b><em>
            Does your module execute any long-running tasks?
            
            
        </em></font>
<p></p>
<b>Answer:</b>
No.
<p></p>
<font color="gray"><b><a name="answer-perf-huge_dialogs">Question (perf-huge_dialogs)</a>:</b><em>
            Does your module contain any dialogs or wizards with a large number of
            GUI controls such as combo boxes, lists, trees, or text areas?
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-huge_dialogs
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-perf-menus">Question (perf-menus)</a>:</b><em>
            Does your module use dynamically updated context menus, or
            context-sensitive actions with complicated and slow enablement logic?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-menus
  </p>
 
<p></p>
<font color="gray"><b><a name="answer-perf-spi">Question (perf-spi)</a>:</b><em>
            How the performance of the plugged in code will be enforced?
            
        </em></font>
<p></p>
<b>Answer:</b>
  
<p>
   XXX no answer for perf-spi
  </p>
 
</ul>
    
    
    <!-- security -->
    <!-- recovery -->
    

</api-questions>





 

 

 

 



  













<!-- Question: compat-i18n

     <question id="compat-i18n">
            Is your module correctly internationalized?
            <hint>
            Correct internationalization means that it obeys instuctions 
            at <a href="http://www.netbeans.org/devhome/docs/i18n/index.html">
            NetBeans I18N pages</a>.
            </hint>
        </question>
-->




<!-- Question: compat-standards

     <question id="compat-standards">
            Does the module implements or defines any standards? Is the 
            implementation exact or it deviates somehow?
        </question>
-->




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




<!-- Question: dep-jre

     <question id="dep-jre">
            Which version of JRE you need (1.2, 1.3, 1.4, etc.)?
            <hint>
            It is expected that if your module runs on 1.x that it will run 
            on 1.x+1 if no, state that please. Also describe here cases where
            you run different code on different versions of JRE and why.
            </hint>
        </question>
-->




<!-- Question: dep-jrejdk

     <question id="dep-jrejdk">
            Do you require JDK or is JRE enough?
        </question>
-->




<!-- Question: dep-nb

     <question id="dep-nb">
            What other NetBeans projects this one depends on?
            <hint>
            If you want, describe such projects as imported API using
            the <code>&lt;api name="identification" type="import or export" category="stable" url="where is the description" /&gt;</code>
            </hint>
        </question>
-->




<!-- 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
            (see <a href="http://libs.netbeans.org">libraries</a>) and
            it is prefered to use this approach when more modules may
            depend on such third-party library.
            </hint>
        </question>
-->




<!-- Question: dep-platform

     <question id="dep-platform">
            On which platforms your module run? Any? Does it run in the same
            way?
            <hint>
            If your module is using JNI or deals with special differences of
            OSes like filesystems, etc. please describe here what they are.
            </hint>
        </question>
-->




<!-- Question: deploy-jar

     <question id="deploy-jar">
            Do you deploy just module JAR file(s) or some other files?
            <hint>
            If your module consist just from one module JAR file, just confirm that.
            If it uses more than one JAR, describe where there are located, how
            they refer to each other. 
            If it consist of module JAR(s) and other files, please describe
            what is their purpose, why other files are necessary. Please 
            make sure that installation/deinstallation leaves the system 
            in state as it was before installation.
            </hint>
        </question>
-->



<!--
        <question id="deploy-dependencies" when="final">
            What do other modules need to do to declare a dependency on this one?
            <hint>
                Provide a sample of the actual lines you would add to a module manifest
                to declare a dependency, for example using OpenIDE-Module-Module-Dependencies
                or OpenIDE-Module-Requires. You may use the magic token @SPECIFICATION-VERSION@
                to represent the current specification version of the module.
            </hint>
        </question>
-->
 


<!-- Question: deploy-nbm

     <question id="deploy-nbm">
            Can you deploy NBM via AutoUpdate center?
            <hint>
            If not why?
            </hint>
        </question>
-->




<!-- 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
            whenever possible (<a href="http://www.netbeans.org/download/apis/org/openide/doc-files/upgrade.html#3.4-public-packages">
            public packages
            </a>). 
            </hint>
        </question>
-->




<!-- Question: deploy-shared

     <question id="deploy-shared">
            Do you need to be installed in shared location or only in user directory?
            <hint>
            Installation location shall not matter, if it does explain why.
            </hint>
        </question>
-->




<!-- Question: exec-classloader

     <question id="exec-classloader">
            Does your code uses own classloader?
            <hint>
            A bit unusual. Please explain why and what for.
            </hint>
        </question>
-->




<!-- Question: exec-component

     <question id="exec-component">
            Is execution of your code influenced by (string) property
            of any of your components?
            
            <hint>
            Often <code>JComponent.getClientProperty</code>, <code>Action.getValue</code>
            or <code>PropertyDescriptor.getValue</code>, etc. are used to influence
            a behaviour of some code. This of course forms an interface that should
            be documented. Also if one depends on some interface that an object
            implements (<code>component instanceof Runnable</code>) that forms an
            API as well.
            </hint>
        </question>
-->




<!-- Question: exec-privateaccess

     <question id="exec-privateaccess">
            Are you aware of any other part 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>
-->




<!-- Question: exec-property

     <question id="exec-property">
            Is execution of your code influenced by any environment of
            system (<code>System.getProperty</code>) property?
            
            <hint>
            If there is a property that can change the behaviour of your 
            code, somebody will likely use it. You should describe what it does 
            and the stability category of this API. You may use
            <PRE>
                &lt;property name="id" category="private" &gt;
                    description of the property, where it is used, what it influence, etc.
                &lt;/property&gt;            
            </PRE>
            </hint>
        </question>
-->




<!-- Question: exec-reflection

     <question id="exec-reflection">
            Does your code uses java.lang.reflect to execute some other code?
            <hint>
            This usually indicates a missing or unsufficient 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>
-->



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




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




<!-- Question: perf-startup

     <question id="perf-startup">
            Does your module executes anything on startup?
        </question>
-->




<!-- Question: perf-wakeup

     <question id="perf-wakeup">
            Is any piece of your code waking up periodically?
        </question>
-->




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




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




<!-- Question: resources-mask

     <question id="resources-mask">
            Does your module mask/hide/override any resource provided by another one in
            module layer? 
            
            <hint>
            If you mask a file provided by another module, you probably depend
            on that and do not want the other module to (for example) change
            the file's name. That module shall thus make that file available as an API
            of some stability category.
            </hint>
        </question>
-->




<!-- Question: resources-read

     <question id="resources-read">
            Does your module read any resources from layers? For what purpose?
            
            <hint>
            As this is some kind of intermodule dependency, it is a kind of API.
            Please describe it and clasify according to 
            <a href="http://openide.netbeans.org/tutorial/api-design.html#categories">
            common stability categories</a>.
            </hint>
        </question>
-->








 



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



 

 




<!--
        <question id="format-clipboard" when="impl">
            Which data flavors (if any) does your code read from or insert to
            the clipboard (by access to clipboard on means calling methods on <code>java.awt.datatransfer.Transferable</code>?
            
            <hint>
            Often Node's deal with clipboard by usage of <code>Node.clipboardCopy, Node.clipboardCut and Node.pasteTypes</code>.
            Check your code for overriding these methods.
            </hint>
        </question>
-->
 



<!--
        <question id="format-dnd" when="impl">
            Which protocols (if any) does your code understand during Drag &amp; Drop?
            <hint>
            Often Node's deal with clipboard by usage of <code>Node.drag, Node.getDropType</code>. 
            Check your code for overriding these methods. Btw. if they are not overridden, they
            by default delegate to <code>Node.clipboardCopy, Node.clipboardCut and Node.pasteTypes</code>.
            </hint>
        </question>
-->
 



<!--
        <question id="format-types" when="impl">
            Which protocols and file formats (if any) does your module read or write on disk,
            or transmit or receive over the network? Do you generate an ant build script?
            Can it be edited and modified? 
            
            <hint>
            <p>
            Files can be read and written by other programs, modules and users. If they influence
            your behaviour, make sure you either document the format or claim that it is a private
            api (using the &lt;api&gt; tag). 
            </p>
            
            <p>
            If you generate an ant build file, this is very likely going to be seen by end users and
            they will be attempted to edit it. You should be ready for that and provide here a link
            to documentation that you have for such purposes and also describe how you are going to
            understand such files during next release, when you (very likely) slightly change the 
            format.
            </p>
            </hint>
        </question>
-->
 



<!--
        <question id="lookup-lookup" when="init">
            Does your module use <code>org.openide.util.Lookup</code>
            or any similar technology to find any components to communicate with? Which ones?
            
            <hint>
            Please describe the interfaces you are searching for, where 
            are defined, whether you are searching for just one or more of them,
            if the order is important, etc. Also classify the stability of such
            API contract. For that use &lt;api group=&amp;lookup&amp; /&gt; tag.
            </hint>
        </question>
-->
 



<!--
        <question id="lookup-register" when="final">
            Do you register anything into lookup for other code to find?
            <hint>
            Do you register using layer file or using <code>META-INF/services</code>?
            Who is supposed to find your component?
            </hint>
        </question>
-->
 



<!--
        <question id="lookup-remove" when="final">
            Do you remove entries of other modules from lookup?
            <hint>
            Why? Of course, that is possible, but it can be dangerous. Is the module
            your are masking resource from aware of what you are doing?
            </hint>
        </question>
-->
 



<!--
        <question id="perf-exit" when="final">
            Does your module run any code on exit?
        </question>
-->
 



<!--
        <question id="perf-huge_dialogs" when="final">
            Does your module contain any dialogs or wizards with a large number of
            GUI controls such as combo boxes, lists, trees, or text areas?
        </question>
-->
 



<!--
        <question id="perf-limit" when="init">
            Are there any hard-coded or practical limits in the number or size of
            elements your code can handle?
        </question>
-->
 



<!--
        <question id="perf-mem" when="final">
            How much memory does your component consume? Estimate
            with a relation to the number of windows, etc.
        </question>
-->
 



<!--
        <question id="perf-menus" when="final">
            Does your module use dynamically updated context menus, or
            context-sensitive actions with complicated and slow enablement logic?
            <hint>
                If you do a lot of tricks when adding actions to regular or context menus, you can significantly
                slow down display of the menu, even when the user is not using your action. Pay attention to
                actions you add to the main menu bar, and to context menus of foreign nodes or components. If
                the action is conditionally enabled, or changes its display dynamically, you need to check the
                impact on performance. In some cases it may be more appropriate to make a simple action that is
                always enabled but does more detailed checks in a dialog if it is actually run.
            </hint>
        </question>
-->
 



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



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



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


</api-answers>
</body>
</html>