oracle.ide.externaltools

Class ExternalTool

java.lang.Object

oracle.ide.externaltools.ExternalTool

All Implemented Interfaces:

Copyable

Direct Known Subclasses:

LazyExternalTool

public abstract class ExternalTool
extends java.lang.Object
implements Copyable

The base class for external tools.

Note that it's generally the responsibility of the tool manager (in conjunction with type implementations) to create new instances of ExternalTools. If you construct a new tool manually, it may not be initialized properly.

Many of the methods on this class are deprecated since the 11.1.1 release. The external tools framework now uses HashStructure to store persistent properties for tools.

Following the standard idiom, you can obtain a typesafe "bean-like" object that provides access to these properties by using an appropriate implementation of HashStructureAdapter. A HashStructureAdapter providing access to most of the deprecated properties on this class is available in ExternalToolBaseProperties. You can obtain an instance like so:

   ExternalToolBaseProperties props = ExternalToolBaseProperties.getInstance( tool );
   String caption = props.getCaption();
 

It is almost always better to access properties using the adapter than through the deprecated methods on this class, especially if you are applying batch operations to a single external tool.

Field Summary

Fields

Modifier and Type	Field and Description
static int	AVAIL_ALWAYS Deprecated. since 11.1.1. Use ExternalToolBaseProperties.getAvailability() or ExternalToolBaseProperties.setAvailability(Availability).
static int	AVAIL_REGEXP Deprecated. since 11.1.1. Use ExternalToolBaseProperties.getAvailability() or ExternalToolBaseProperties.setAvailability(Availability).
static int	AVAIL_SELECTION Deprecated. since 11.1.1. Use ExternalToolBaseProperties.getAvailability() or ExternalToolBaseProperties.setAvailability(Availability).
static int	AVAIL_TYPES Deprecated. since 11.1.1. Use ExternalToolBaseProperties.getAvailability() or ExternalToolBaseProperties.setAvailability(Availability).
static int	INTEG_CODE_EDITOR_CONTEXT_MENU_ITEM Deprecated. since 11.1.1. Use ExternalToolBaseProperties.isIntegrated(IntegrationPoint) or ExternalToolBaseProperties.setIntegrated(IntegrationPoint, boolean)
static int	INTEG_MAIN_WINDOW_TOOLBAR_BUTTON Deprecated. since 11.1.1. Use ExternalToolBaseProperties.isIntegrated(IntegrationPoint) or ExternalToolBaseProperties.setIntegrated(IntegrationPoint, boolean)
static int	INTEG_NAVIGATOR_CONTEXT_MENU_ITEM Deprecated. since 11.1.1. Use ExternalToolBaseProperties.isIntegrated(IntegrationPoint) or ExternalToolBaseProperties.setIntegrated(IntegrationPoint, boolean)
static int	INTEG_NAVIGATOR_TOOLBAR_BUTTON Deprecated. since 11.1.1. This integration has never been supported.
static int	INTEG_TOOLS_MENU_ITEM Deprecated. since 11.1.1. Use ExternalToolBaseProperties.isIntegrated(IntegrationPoint) or ExternalToolBaseProperties.setIntegrated(IntegrationPoint, boolean)

Constructor Summary

Constructors

Constructor and Description
ExternalTool()

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.Object	copyTo(java.lang.Object target) Copies the internal state of this object to the specified copy.
protected void	copyToImpl(ExternalTool copy) Deprecated. since 11.1.1 with no replacement. The persistence mechanism for external tools changed in the 11.1.1 release, and no longer requires subclasses to implement this method.
boolean	equals(java.lang.Object o)
int	getAvailability() Deprecated. since 11.1.1 - use ExternalToolBaseProperties.getAvailability().
java.lang.String	getAvailabilityExpression() Deprecated. since 11.1.1 with no replacement. Support for regular expression availability was dropped in 10.1.3.
java.util.List<java.lang.String>	getAvailableTypes() Deprecated. since 11.1.1 - use ExternalToolBaseProperties.getAvailableTypes().
java.lang.String	getCaption() Deprecated. since 11.1.1 - use ExternalToolBaseProperties.getCaption().
HashStructure	getData() Gets persistent properties of this tool.
java.net.URL	getIconURL() Deprecated. since 11.1.1 - use ExternalToolBaseProperties.getIconURL().
javax.swing.Icon	getIconWhenRequired() If an external tool is displayed in the toolbar, an icon is required.
int	getIntegrationMask() Deprecated. since 11.1.1 - use ExternalToolBaseProperties.isIntegrated(IntegrationPoint).
boolean	getReloadBuffers() Deprecated. since 11.1.1 - use ExternalToolBaseProperties.getReloadBuffers()
java.lang.String	getScannerTag() Deprecated. since 11.1.1 - use ExternalToolBaseProperties.getScannerTag()
java.lang.String	getToolTipText() Deprecated. since 11.1.1 - use ExternalToolBaseProperties.getToolTipText().
int	hashCode()
boolean	hasIntegration(int integrationType) Deprecated. since 11.1.1 - use ExternalToolBaseProperties.isIntegrated(IntegrationPoint).
void	initializeExternalTool() Perform any work necessary to initialize a newly-created instance of the external tool
abstract void	run(ExternalToolManager manager, Context context) Invoke the external tool instance on the specified context.
void	setAvailability(int availability) Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setAvailability(Availability).
void	setAvailabilityExpression(java.lang.String expression) Deprecated. since 11.1.1 with no replacement. Support for regular expression availability was dropped in 10.1.3.
void	setAvailableTypes(java.util.List<java.lang.String> types) Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setAvailableTypes(List).
void	setCaption(java.lang.String caption) Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setCaption(String).
void	setData(HashStructure hs) Sets persistent properties of this tool.
void	setIconURL(java.net.URL u) Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setIconURL(URL).
void	setIntegrationMask(int integrationMask) Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setIntegrated(IntegrationPoint,boolean).
void	setReloadBuffers(boolean reload) Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setReloadBuffers(boolean)
void	setScannerTag(java.lang.String tag) Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setScannerTag(String)
void	setToolTipText(java.lang.String toolTipText) Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setToolTipText(String).
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

INTEG_TOOLS_MENU_ITEM

public static final int INTEG_TOOLS_MENU_ITEM

Deprecated. since 11.1.1. Use ExternalToolBaseProperties.isIntegrated(IntegrationPoint) or ExternalToolBaseProperties.setIntegrated(IntegrationPoint, boolean)

See Also:

Constant Field Values

INTEG_CODE_EDITOR_CONTEXT_MENU_ITEM

public static final int INTEG_CODE_EDITOR_CONTEXT_MENU_ITEM

Deprecated. since 11.1.1. Use ExternalToolBaseProperties.isIntegrated(IntegrationPoint) or ExternalToolBaseProperties.setIntegrated(IntegrationPoint, boolean)

See Also:

Constant Field Values

INTEG_NAVIGATOR_CONTEXT_MENU_ITEM

public static final int INTEG_NAVIGATOR_CONTEXT_MENU_ITEM

Deprecated. since 11.1.1. Use ExternalToolBaseProperties.isIntegrated(IntegrationPoint) or ExternalToolBaseProperties.setIntegrated(IntegrationPoint, boolean)

See Also:

Constant Field Values

INTEG_MAIN_WINDOW_TOOLBAR_BUTTON

public static final int INTEG_MAIN_WINDOW_TOOLBAR_BUTTON

Deprecated. since 11.1.1. Use ExternalToolBaseProperties.isIntegrated(IntegrationPoint) or ExternalToolBaseProperties.setIntegrated(IntegrationPoint, boolean)

See Also:

Constant Field Values

INTEG_NAVIGATOR_TOOLBAR_BUTTON

public static final int INTEG_NAVIGATOR_TOOLBAR_BUTTON

Deprecated. since 11.1.1. This integration has never been supported.

See Also:

Constant Field Values

AVAIL_ALWAYS

public static final int AVAIL_ALWAYS

Deprecated. since 11.1.1. Use ExternalToolBaseProperties.getAvailability() or ExternalToolBaseProperties.setAvailability(Availability).

See Also:

Constant Field Values

AVAIL_SELECTION

public static final int AVAIL_SELECTION

Deprecated. since 11.1.1. Use ExternalToolBaseProperties.getAvailability() or ExternalToolBaseProperties.setAvailability(Availability).

See Also:

Constant Field Values

AVAIL_REGEXP

public static final int AVAIL_REGEXP

Deprecated. since 11.1.1. Use ExternalToolBaseProperties.getAvailability() or ExternalToolBaseProperties.setAvailability(Availability).

See Also:

Constant Field Values

AVAIL_TYPES

public static final int AVAIL_TYPES

Deprecated. since 11.1.1. Use ExternalToolBaseProperties.getAvailability() or ExternalToolBaseProperties.setAvailability(Availability).

See Also:

Constant Field Values

Constructor Detail

ExternalTool

public ExternalTool()

Method Detail

setData

public final void setData(HashStructure hs)

Sets persistent properties of this tool. This method is normally called automatically by the external tools framework when it creates instances of this class.

Parameters:

hs - persistent properties of this tool.

Throws:

java.lang.NullPointerException - if hs is null.

Since:

11.1.1

getData

public final HashStructure getData()

Gets persistent properties of this tool.

Normally, an external tool implementation will retrieve specific typed properties from this structure using a HashStructureAdapter. For example, to obtain general properties of a tool, use:

   ExternalToolProperties properties = ExternalToolProperties.getInstance( 
     myTool )
 

Returns:

the persistent properties of this tool. Will never return null.

Since:

11.1.1

setScannerTag

public void setScannerTag(java.lang.String tag)

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setScannerTag(String)

An ExternalToolScanner that creates a tool can set a tag on the tool so that it can identify whether the tool has been created in future.

Parameters:

tag - a tag recognized by the scanner that created this tool

getScannerTag

public java.lang.String getScannerTag()

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.getScannerTag()

Get the scanner tag for this tool.

Returns:

the scanner tag for this tool.

getReloadBuffers

public boolean getReloadBuffers()

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.getReloadBuffers()

Get whether buffers will be reloaded after running this tool. Subclasses are responsible for ensuring that this request is honored after running the tool.

Returns:

true if the IDE's buffers are reloaded after running.

setReloadBuffers

public void setReloadBuffers(boolean reload)

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setReloadBuffers(boolean)

Set whether to reload buffers after running this tool

Parameters:

reload - if true, the tool will force a buffer reload

getIconWhenRequired

public javax.swing.Icon getIconWhenRequired()

If an external tool is displayed in the toolbar, an icon is required. This method should return the icon to use for this external tool when no icon has been specified for the user, but the tool is present in the toolbar.

Subclasses may override this to provide a type specific default icon. This implementation returns a default document icon.

Returns:

an icon. Must not return null.

hasIntegration

public boolean hasIntegration(int integrationType)

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.isIntegrated(IntegrationPoint).

Is this tool integrated in the specified way? Utility method, equivalent to ((getIntegrationMask() & integrationType) != 0)

Parameters:

integrationType - one of the INTEG_ constants defined in this class.

Returns:

true if this tool has the specified integration.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

setAvailableTypes

public void setAvailableTypes(java.util.List<java.lang.String> types)

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setAvailableTypes(List).

Set the types this tool is available on, if the availability type is set to AVAIL_TYPES.

Parameters:

types - a list of class names, which should match class names in oracle.ide.config.DocumentExtensions.DocRecord.getDocClass().

getAvailableTypes

public java.util.List<java.lang.String> getAvailableTypes()

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.getAvailableTypes().

Get the types this tool is available on, if the availability type is set to AVAIL_TYPES.

Returns:

a list of class names, which should match class names in oracle.ide.config.DocumentExtensions.DocRecord.getDocClass().

getIconURL

public java.net.URL getIconURL()

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.getIconURL().

Get the URL of the icon for this external tool.

Returns:

a URL pointing to an icon file to use for this tool. If null, no icon will be used.

setIconURL

public void setIconURL(java.net.URL u)

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setIconURL(URL).

Set the URL of the icon for this external tool.

Parameters:

u - a URL pointing to an icon file to use for this tool. If null, no icon will be used.

getCaption

public java.lang.String getCaption()

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.getCaption().

Get the caption for this external tool. If the caption contains an ampersand character, the subsequent character will be used as the mnemonic when this tool is displayed in menus.

Returns:

a String caption for the tool. Must not be null.

setCaption

public void setCaption(java.lang.String caption)

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setCaption(String).

Set the caption for this external tool. If the caption contains an ampersand character, the subsequent character will be used as the mnemonic when this tool is displayed in menus.

Parameters:

caption - a String caption for the tool. Must not be null.

getToolTipText

public java.lang.String getToolTipText()

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.getToolTipText().

Get the tool tip text for this tool.

Returns:

a String to be used as tool tip text for the tool. May be null.

setToolTipText

public void setToolTipText(java.lang.String toolTipText)

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setToolTipText(String).

Set the tool tip text for this tool.

Parameters:

toolTipText - a String to be used as tool tip text for the tool. May be null.

getIntegrationMask

public int getIntegrationMask()

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.isIntegrated(IntegrationPoint).

Get the types of integration this tool has with the IDE.

Returns:

a bitmask of IT_ constants from this interface.

setIntegrationMask

public void setIntegrationMask(int integrationMask)

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setIntegrated(IntegrationPoint,boolean).

Set the types of integration this tool has with the IDE.

Parameters:

integrationMask - a bitmask of IT_ constants from this interface.

getAvailability

public int getAvailability()

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.getAvailability().

Get when this tool is available.

Returns:

one of the AVAIL_ constants from this interface.

setAvailability

public void setAvailability(int availability)

Deprecated. since 11.1.1 - use ExternalToolBaseProperties.setAvailability(Availability).

Set when this tool is available.

Parameters:

availability - one of the AVAIL_ constants from this interface.

getAvailabilityExpression

public java.lang.String getAvailabilityExpression()

Deprecated. since 11.1.1 with no replacement. Support for regular expression availability was dropped in 10.1.3.

Returns:

the empty string.

setAvailabilityExpression

public void setAvailabilityExpression(java.lang.String expression)

Deprecated. since 11.1.1 with no replacement. Support for regular expression availability was dropped in 10.1.3.

Does nothing.

Parameters:

expression - ignored.

copyToImpl

protected void copyToImpl(ExternalTool copy)

Deprecated. since 11.1.1 with no replacement. The persistence mechanism for external tools changed in the 11.1.1 release, and no longer requires subclasses to implement this method.

Does nothing.

copyTo

public java.lang.Object copyTo(java.lang.Object target)

Description copied from interface: Copyable

Copies the internal state of this object to the specified copy. If copy is null, then this method should create a new instance of this class and proceed to copy the internal state to the newly created object. Generally, only the persistent state of the object should be copied, but whether or not it is appropriate to copy transient properties is at the discretion of the individual implementor.

Regardless of whether the copy occurs to an existing object or to a newly created object, the return value is object to which this object's state was copied.

There is a standard implementation pattern for the copyTo method that helps avoid problems that arise when a Copyable object is subclassed. The pattern is:

    public Object copyTo( Object target )
    {
      final <this_class> copy =
        target != null ? (<this_class>) target : new <this_class>();
      copyToImpl( copy );
      return copy;
    }

    protected final void copyToImpl( <this_class> copy )
    {
      super.copyToImpl( copy );  //  if necessary
      //  put code here for copying the properties of <this_class>
    }
  

The parameter passed into the copyToImpl method is the same type of this class. The responsibility of copyToImpl is to copy the state of this class through direct access of the fields. The copyToImpl method should not use getters and setters since these may be overridden, causing the state of this class to be incompletely copied.

Specified by:

copyTo in interface Copyable

Parameters:

target - The target object to which the state of this object should be copied. If target is null, then the copyTo method will return a new instance of this class.

Returns:

The object to which the state of this object was copied. If the target was non-null, then the return value is the same as the target object that was passed in; otherwise, the return value is a new instance of this class.

run

public abstract void run(ExternalToolManager manager,
       Context context)
                  throws ToolRunException

Invoke the external tool instance on the specified context.

Parameters:

context - the IDE context the tool was invoked in.

Throws:

ToolRunException - if the tool failed to run.

initializeExternalTool

public void initializeExternalTool()

Perform any work necessary to initialize a newly-created instance of the external tool