Package oracle.ide.externaltools.macro

Contains APIs related to macros that can be expanded when invoking external tools.

See: Description

Interface Summary

Interface	Description
MacroPicker	Interface to the macro picker UI.

Class Summary

Class	Description
MacroExpander	Macro expanders are registered with the MacroRegistry and can be used to expand macros prior to running external tools.
MacroRegistry	Macros use information from the current JDeveloper context to pass into or influence the behavior of external tools.
MacroTextField	A text field that will display a completion insight popup when the user starts typing a macro.
Parameter	A parameter in a parameterized external tool macro.
ParameterizedMacro	A parameterized macro takes one or more parameters that can be used at expansion time.

Package oracle.ide.externaltools.macro Description

Contains APIs related to macros that can be expanded when invoking external tools.

Macros are available to external tool definitions. These are expanded when a tool is invoked and can use information from the current IDE context (e.g. the selected file).

Querying Existing Macro Definitions

The MacroRegistry contains definitions of all macros available to external tools. You can obtain an instance of MacroRegistry from ExternalToolManager.getMacroRegistry().

To query all existing macro definitions, use the MacroRegistry.iterator() method. The elements in the iterator are all instances of MacroExpander.

Obtaining Macro UI Controls

Extension writers can retrieve instances of the macro-related user interface controls that the Create External Tool wizard uses.

MacroPicker is a control which contains a list of all available macros and descriptions of each. You can obtain a MacroPicker using MacroRegistry.getPicker(ExternalToolType, boolean). The picker can be displayed in a dialog via MacroPicker.runDialog(Component), or embedded in other UI using MacroPicker.getComponent().

MacroTextField is a control that provides an insight-like popup when the user types a partial macro and pauses for a short period of time. Use the MacroRegistry.getTextField(ExternalToolType,boolean) method to retrieve an instance of MacroTextField.

Expanding Macros

You can expand macros in a string in conjunction with a Context. Use the MacroRegistry.expand(String,oracle.ide.Context,boolean) method to perform an expansion. Any recognized escaped macro strings in the specified string will be expanded using the relevant MacroExpander.expand(Context ) method. For example, if the string "This is a ${macro.expansion} test" is passed as the first parameter, and there is a MacroExpander instance registered with the MacroRegistry with a getMacro() method that returns "macro.expansion", then that portion of the original string will be replaced with the return value of expand() on the MacroExpander instance.

Registering Custom Macros

Extensions can easily plug additional macros into external tools. Write a class that implements the MacroExpander interface, then register it in extension.xml. The following example code demonstrates a simple MacroExpander implementation and the registration code.

 import java.net.URL;

 import oracle.ide.Context;
 import oracle.ide.model.DefaultDisplayable;
 import oracle.ide.model.Locatable;
 import oracle.ide.net.URLFileSystem;

 import oracle.ide.externaltools.ExternalToolType;
 import oracle.ide.externaltools.macro.MacroExpander;

 public class DemoMacro extends DefaultDisplayable implements MacroExpander
 {
   public String getShortLabel()
   {
     return "Demo Macro";
   }

   public String getLongLabel()
   {
     return "An example macro for external tools - expands to the first letter "+
       "of the filename of the selected file.";
   }

   public String expand( Context context )
   {
     URL u = null;

     if ( context.getSelection() != null )
     {
       // This handles the case when there is a selection in a view (e.g.
       // the applications navigator)
       if ( context.getSelection().length == 1 && 
            context.getSelection()[0] instanceof Locatable)
       {
         u = ((Locatable)context.getSelection()[0]).getURL();
       }
     }

     if ( u == null )
     {
       // This handles the case when an editor for a document (e.g. the 
       // code editor) is the active view. 
       if ( context.getDocument() != null )
       {
         u = context.getDocument().getURL();
       }
     }

     if ( u != null )
     {
       String fullPath = URLFileSystem.getPlatformPathName( u );
       if ( fullPath != null && fullPath.length() > 0 )
       {
         return fullPath.substring( 0, 1 );
       }
     }
     // It's OK to return null if you can't expand the context - the macro
     // will just be expanded to an empty string.
     return null;
   }

   public String getSampleExpansion( Context context )
   {
     return expand( context );
   }

   public String getMacro()
   {
     return "demo.macro";   // NOTRANS
   }

   public boolean isDirectoryMacro()
   {
     return false;
   }

   public boolean isAvailableForType( ExternalToolType type )
   {
     return true;
   }
 }
 

The following registration code is used in extension.xml:

     <extension ...>
       <hooks>
         <externaltools xmlns="http://xmlns.oracle.com/ide/extension">
           <macros>
             <macro-class>org.foo.MyScannerClass</macro-class>
           </macros>
         </externaltools>
       </hooks>
     </extension>
 

Since:

10.1.3