This extension point is for defining actions that appear in the popup menu of remote resources of the Remote Systems view, in the Remote System Explorer perspective. It is modelled after the Eclipse workbench extension point <samp>org.eclipse.ui.popupMenus</samp>. However, because we know we are targeting remote resources, it is simplified a bit. Specifically, there is no need to specify the object class, as we assume these actions apply to remote resources, which often share a common object class. On the other hand, we need additional filtering capabilities to scope which remote resources these actions are to apply to. To this end, there is a rich set of filtering attributes to enable fine-grained scoping by a number of criteria. These scoping attributes are the same as those for our <samp>org.eclipse.rse.ui.propertyPages</samp> extension point. Like the workbench extension point, unless you specify otherwise , the action will show up in the main popup menu in the "additions" group. To create cascading sub-menus, first define a submenu and named separator group within it, using the <samp>menu</samp> element and its <samp>separator </samp> sub-element. Then refer to that menu's <samp>id</samp> in your action element's <samp>menubarPath</samp> attribute: <samp>menuid/separator-group-name</samp>. While not fully documented here, this extension point supports the <samp><filter></samp> <samp><visibility></samp> and <samp><enablement></samp> elements from the <samp>org.eclipse.ui.popupMenus</samp> extension point. See its documentation in the help for information on these elements. For example: <samp><pre> <filter name="subsystemConfigurationCategory" value="files"/> <enablement> <objectState name="hasChildren" value="true"/> </enablement> </pre></samp> These elements are for conditionally deciding whether to show, or enable, the action(s). The <samp>name</samp>s supported for the <samp><filter></samp> element, and the <samp>objectState</samp>s supported for the <samp><visibility></samp> and <samp><enablement></samp> elements are: <ul> <li><samp>"name"</samp>. Will test the value for an exact match on an object's name, or beginning-of-name match if ends with an asterisk. <li><samp>"type"</samp>. Will test the value for an exact match on an object's type. <li><samp>"offline"</samp>.Will test the value against "true" if the user is working in "offline" mode or "false" if not. Currently only supported for iSeries connections. <li><samp>"connected"</samp>. Will test the value against "true" if the connection containing the selected object is active or "false" if not. <li><samp>"hasChildren"</samp>. Will test the value against "true" if this object's adapter reports that it has children or "false" if it doesn't have children. <li><samp>"systemType"</samp>. Will test the value for an exact match on the system type of this object's parent SystemConnection object. You can specify multiple values if you comma-separate them. <li><samp>"subsystemConfigurationId"</samp>. Will test the value for an exact match on the <samp>ID</samp> of the subsystem configuration that created this object's subsystem. Returns false for SystemConnection objects. You can specify multiple values if you comma-separate them. <li><samp>"subsystemConfigurationCategory"</samp>. Will test the value for an exact match on the <samp>category</samp> of the subsystem configuration that created this object's subsystem. You can specify multiple values if you comma-separate them. </ul> These <samp>objectstate</samp>s are also supported via the Eclipse <samp>org.eclipse.ui.popupMenus</samp> extension point, for the non-remote objects in the RSE: connections, subsystems, filter pools and filters. (no description available) (no description available) The id for this set of remote resource popup menu contributions. Must be unique over all plug-ins. It is suggested that the user qualify this with the plug-in id. One of the optional filters to scope the remote resources for which the popup menu actions are to appear. Specify as many of these optional filters like this as needed to explicitly scope all the actions defined in this objectContribution element. This filter specifies a subsystem configuration id, such that these actions will only appear for remote resources returned from subsystems of the given subsystem configuration. This ID can be scalar, or it can be generic to match on multiple subsystem configuration IDs. One of the optional filters to scope the remote resources for which the popup menu actions are to appear. Specify as many of these optional filters like this as needed to explicitly scope all the actions defined in this <samp>objectContribution</samp> element. This filter specifies a subsystem configuration category, such that these actions will only appear for remote resources returned from subsystems owned by factories declared defined with the specified category. This category can be scalar, or it can be generic to match on multiple subsystem configuration categories. The categories of the IBM-supplied subsystem factories that display remote resources in the Remote Systems view are: <ul> <li>files. For subsystems that list hierarchical file system resources, such as folders and files. <li>nativefiles. For subsystems that list non-hierarchical file system resources, such as in the iSeries QSYS file system. <li>commands. For subsystems that list remote commands. <li>jobs. For subsystems that list remote jobs. </ul> One of the optional filters to scope the remote resources for which the popup menu actions are to appear. Specify as many of these optional filters like this as needed to explicitly scope all the actions defined in this objectContribution element. This filter specifies a single system type, or semicolon-separated list of system types, or asterisk for all system types (the default). Will scope these actions to only remote objects from systems of this type or types. One of the optional filters to scope the remote resources for which the popup menu actions are to appear. Specify as many of these optional filters like this as needed to explicitly scope all the actions defined in this objectContribution element. This filter specifies a simple or generic resource name. Only resources whose name matches this filter will show the actions defined within this object contribution element. One of the optional filters to scope the remote resources for which the property page is to appear. Specify as many of these optional filters like this as needed to explicitly scope this property page element. This filter specifies a type category. Normally the subsystemconfigurationid is sufficient, but some subsystems display multiple types of resources, and these are categorized by a type name that can be used to scope property pages. Here are the type categories supported by IBM- supplied subsystems: <ul> <li>files. For hierarchical file systems resources. <li>commands. For remote commands. <li>jobs. For remote jobs. </ul> The IBM-supplied subsystem for iSeries native file system objects also supports these type categories: <ul> <li>LIBRARIES. Set for libraries. <li>OBJECTS. Set for objects, excluding files. <li>OBJECTFILES. Set for file objects. Use <samp>OBJECTS*</samp> to match on all objects. <li>MEMBERS. Set for data and source file members. <li>RECORDS. Set for record formats within files. <li>FIELDS. Set for fields within record formats. <li>MESSAGE_DESCRIPTIONS. Set for messages within message files. </ul> One of the optional filters to scope the remote resources for which the popup menu actions are to appear. Specify as many of these optional filters like this as needed to explicitly scope all the actions defined in this objectContribution element. This filter specifies a resource type, either simple or generic. The resource types depends on the subsystem. The types for IBM-supplied subsystems which support them are: <ul> <li>filesXXX. Either folder or file. <li>files400. This is the object's type (for objects), such as *PGM, or member's type (for members), such as RPGLE. Since * is a valid character in an iSeries object type, use %ast. instead of * to prevent wildcard matching. For example, to prevent matching on both *PGM and *SRVPGM, use %ast.PGM for the type. </ul> One of the optional filters to scope the remote resources for which the popup menu actions are to appear. Specify as many of these optional filters like this as needed to explicitly scope all the actions defined in this objectContribution element. This filter specifies a simple or generic resource subtype to match. Not all subsystems support subtypes for their resources. The IBM-supplied subsystems that do support this are: <ul> <li>FilesXXX. This can be either subfolder for nested folders only, or root for the root folder or Windows' drives. <li>Files400. For iSeries objects within a library, this is the object's attribute. For members, it is either DTA or SRC. For fields, it is the field's datatype (a single character). </ul> One of the optional filters to scope the remote resources for which the popup menu actions are to appear. Specify as many of these optional filters like this as needed to explicitly scope all the actions defined in this objectContribution element. This filter specifies a simple or generic resource sub-subtype to match. No IBM-supplied subsystems support sub-subtypes for their resources today. Use this element when you wish to have your action appear in your own cascading menu, versus in the primary popup menu. unique ID for this submenu, used later in the first part of the menubarPath attribute of the action element or path attribute of a nested menu element. This is used to identify the target sub-menu of the action or sub-submenu. readable text to show up in the popup menu, for this cascading menu. Do NOT specify ampersand for mnemonics, as these are assigned for you. However, accelerator information is valid as defined by the Eclipse rules. For multi-cascading menus, use this attribute to identify a previously specified menu that this menu is to be nested within. The syntax is a bit tricky. It is "id/group", where <samp>id</samp> matches the <samp>id</samp> attribute from a previous <samp>menu</samp> element, and <samp>group</samp> matches the <samp>name</samp> attribute of a <samp>separator</samp> sub-element within that previous <samp>menu</samp> element. For the root cascading menu, you can also use this to specify a group within the remote resource's popup menu, where to place this cascading menu. In this case, you would not specify an id. The default group is the <samp>additions</samp> group, which is near the bottom of the popup menu. The IBM pre-defined groups are: <ul> <li>"group.new". This is where the cascading "New->" menu is. <li>"group.goto". This is where the cascading "Goto->" menu is. <li>"group.expandto". This is where the cascading "Expand To->" menu is. <li>"group.openwith". This is where the cascading "Open With->" menu is. <li>"group.browsewith". This is where the cascading "Browse With->" menu is. <li>"group.workwith". This is where the cascading "Work With->" menu is. <li>"group.build". Area of the menu reserved for build or refresh related actions. <li>"group.change". Area of the menu reserved for change-related actions. <li>"group.reorganize". Area of the menu reserved for reorganize-related actions, such as rename, move, copy, delete. <li>"group.reorder". Area of the menu reserved for reorder-related actions, such as move up or move down. <li>"group.generate". Area of the menu reserved for code generation-related actions. <li>"group.search". Area of the menu reserved for search-related actions. <li>"group.connection". Area of the menu reserved for connection-related actions. <li>"group.remoteservers". Area of the menu reserved for the "Remote Servers->" action. <li>"group.importexport". Area of the menu reserved for import or export-related actions. <li>"group.adapter". Area of the menu reserved for actions queried from the remote resource adapters. <li>"additions". Area of the menu reserved for actions that don't specify a group. <li>"group.team". Area of the menu reserved for team-related actions. <li>"group.properties". Area of the menu reserved for properties-related actions. </ul> You may also desire to place your action in an IBM-supplied cascading menu. To do this, for the ID-part, specify one of the following IBM-supplied menu IDs: <ul> <li>"menu.new". This is the cascading "New->" menu. <li>"menu.goto". This is the cascading "Goto->" menu. <li>"menu.expandto". This is the cascading "Expand To->" menu. <li>"menu.openwith". This is the cascading "Open With->" menu. <li>"menu.browsewith". This is the cascading "Browse With->" menu. <li>"menu.workwith". This is the cascading "Work With->" menu. <li>"menu.remoteservers". This is the cascading "Remote Servers->" menu. </ul> Use this element to define an action, and where it will appear in the popup menu. The action defined here will only appear in a remote resource popup menu if the resource matches all the given filtering criteria in the parent objectContribution element. Unique ID for this action. Readable text to display in the popup menu for this action. Do NOT specify ampersand for mnemonics, as these are assigned for you. However, accelerator information is valid, as defined by the Eclipse rules. An optional image icon for the popup menu. This is a .gif file, given with a path relative to your plugin directory. Optional tooltip text for this action. This appears in the status bar when the action is selected. A slash-delimited path that is used to specify the location of the the action in the popup menu. Each token in the path, except the last one, represents an existing submenu in the hierarchy, as defined via the <samp>id</samp> attribute of a <samp>menu</samp> element previously defined. Alternatively, the ID of an IBM-supplied cascading menu can be specified. The last token represents the named separator group into which the action will be added. If no path is given, this must be an IBM-supplied group. See the comments for the path attribute of the menu element for a list of the IBM-supplied cascading menus, and IBM-supplied separator groups. If a path is given, then this must match the name attribute of a <samp>separator</samp> sub-element within one of your <samp>menu</samp> elements. If the path is omitted, or this menubarPath attribute, the action will be added to the standard "additions" group. A value indicating the selection count which must be met to enable the action. If this attribute is specified and the condition is met, the action is enabled. If the condition is not met, the action is disabled. If no attribute is specified, the action is enabled for any number of resources selected. The following formats are supported: <ul> <li>!. 0 items selected. <li>?. 0 or 1 items selected. <li>+. 1 or more items selected. <li>n+. n or more items selected. Example: 2+. <li>n. A precise number of items selected. Example: 4 <li>*. Any number of items selected. </ul> Optional attribute indicating the action is a toggle type. That is, is shown as a check box menu item. The attribute value will be used as the initial state. Optional unique identifier indicating the help context ID for this action. When the action appears as a menu item, pressing F1 while the menu item is highlighted will display help for the given context ID. Your action class that implements <samp>org.eclipse.ui.IObjectActionDelegate</samp>. Typically you will extend one of the IBM-supplied classes, described in the API Information section. Use this element to partition your cascading menu into areas, or groups. This groups are defined in the order in which the separator elements appear. The name attribute identifies the group such that it can be used as the target of an action or sub-menu. The arbitrary, but unique with this menu, name to assign this group. You can specify this name later in the menubarPath attribute of an action, or the group part of the path attribute of a menu. The following is an example of a defining a simple popup menu action for any files and folders in any system type, which only shows when a single file or folder is selected: <h3>Example One</h3> <pre> <extension point="org.eclipse.rse.ui.popupMenus"> <objectContribution id="com.acme.actions.action1" typecategoryfilter="files"> <action id="com.acme.action1" label="Test Action for Files and Folders" class="com.acme.actions.Action1" enablesFor="1"> </action> </objectContribution> </extension> </pre> The following example refines the first example so the action only appears for Java source files, not folders, and only for files in a local connection. Further, we show how to define multiple actions within one objectContribution: <h3>Example Two</h3> <pre> <extension point="org.eclipse.rse.ui.popupMenus"> <objectContribution id="com.acme.actions.action2" typecategoryfilter="files" typefilter="file" namefilter="*.java" subsystemconfigurationid="local.files"> <action id="com.acme.action2a" label="Test Action One for Local Java Files" class="com.acme.actions.Action2a" enablesFor="1"> </action> <action id="com.acme.action2b" label="Test Action Two for Local Java Files" class="com.acme.actions.Action2b" enablesFor="1"> </action> </objectContribution> </extension> </pre> The following example refines the second example, by moving the actions to our own single-cascading menu: <h3>Example Three</h3> <pre> <extension point="org.eclipse.rse.ui.popupMenus"> <objectContribution id="com.acme.actions.action3" typecategoryfilter="files" typefilter="file" namefilter="*.java" subsystemconfigurationid="local.files"> <menu id="com.acme.menu" label="Test Actions"> <separator name="taGroup"/> </menu> <action id="com.acme.action3a" label="Test Action One for Local Java Files" class="com.acme.actions.Action3a" enablesFor="1" menubarPath="com.acme.menu/taGroup"> </action> <action id="com.acme.action3b" label="Test Action Two for Local Java Files" class="com.acme.actions.Action3b" enablesFor="1" menubarPath="com.acme.menu/taGroup"> </action> </objectContribution> </extension> </pre> The following example refines the third example, by moving the actions to our own multiple-cascading menu. Notice how we can define the same separator group in different menus since they are unrelated to each other: <h3>Example Four</h3> <pre> <extension point="org.eclipse.rse.ui.popupMenus"> <objectContribution id="com.acme.actions.action4" typecategoryfilter="files" typefilter="file" namefilter="*.java" subsystemconfigurationid="local.files"> <menu id="com.acme.menu" label="Test Actions"> <separator name="taGroup"/> </menu> <menu id="com.acme.menu2" label="A Sub Menu" path="com.acme.menu/taGroup"> <separator name="taGroup"/> </menu> <action id="com.acme.action4a" label="Test Action One for Local Java Files" class="com.acme.actions.Action4a" enablesFor="1" menubarPath="com.acme.menu/com.acme.menu2/taGroup"> </action> <action id="com.acme.action4a" label="Test Action Two for Local Java Files" class="com.acme.actions.Action4b" enablesFor="1" menubarPath="com.acme.menu/com.acme.menu2/taGroup"> </action> </objectContribution> </extension> </pre> The following example shows how to place actions within an IBM-supplied cascading menu: <h3>Example Five</h3> <pre> <extension point="org.eclipse.rse.ui.popupMenus"> <objectContribution id="com.acme.actions.action5" typecategoryfilter="files" typefilter="file" namefilter="*.java" subsystemconfigurationid="local.files"> <action id="com.acme.action5a" label="Test Action One for Local Java Files" class="com.acme.actions.Action5a" enablesFor="1" menubarPath="menu.openwith/additions"> </action> <action id="com.acme.action5b" label="Test Action Two for Local Java Files" class="com.acme.actions.Action5b" enablesFor="1" menubarPath="menu.browsewith/additions"> </action> </objectContribution> </extension> </pre> Remember, you can repeat the <samp>objectContribution</samp> elements as needed, as well as the <samp>menu</samp> and <samp>action</samp> elements within them. Your actions must all implement the interface <samp>org.eclipse.ui.IObjectActionDelegate</samp>. Typically, you will subclass one of the supplied base classes for this extension point: <ul> <li>org.eclipse.rse.ui.actions.SystemAbstractPopupMenuExtensionAction, in plugin org.eclipse.rse.ui. Base class offering generic support for any remote resource popup menu action, for any system type. <li>org.eclipse.rse.ui.actions.SystemAbstractRemoteFilePopupMenuExtensionAction, in plugin org.eclipse.rse.ui. Specialized base class offering specific support for any remote file or folder popup menu action, for any system type. </ul> There is no supplied implementation for this extension point. Copyright (c) 2002, 2006 IBM Corporation. All Rights Reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html Contributors: IBM Corporation - initial API and implementation