Contents Previous Next

Implementing Operations

Operations are the core of your source code control extension. They define all the actions a user can take throughout the JDeveloper IDE for the source code control system and its files. This section considers how to implement:

Use the oracle.ide.scm.SCMOperation interface to describe operations, but do not implement the interface directly. Instead, create a subclass of one of the following abstract classes in package oracle.ide.scm.op, depending on the type of operation you want to implement:

Superclass

Description

SCMNoFileOperation

Operations that apply to the source code control system or don't require file arguments, e.g. connecting or disconnecting from the system or invoking external tools independent of any files.

SCMToggleOperation

Operations with an on/off state, displayed as checkboxes or menu options, e.g. displaying or hiding a dockable window.

SCMMultiFileOperation

Operations that apply to one or more files, e.g. check in or check out.

SCMSingleFileOperation

Operations that apply to only one file, e.g. view version history or view version events.

Back to top

Control Items

For every type of operation you implement, the operation itself must implement getControlItem(). This method returns an object to describe how the control item (menu option) used to represent the operation should appear.

The object returned should implement oracle.ide.scm.SCMControlItem and oracle.ide.scm.SCMControlItemObject provides an object class with this implementation. Create an instance of this class and describe what the control item should return:

import oracle.ide.scm.SCMControlItem;
import oracle.ide.scm.SCMControlItemObject;
import oracle.ide.scm.op.SCMMultiFileOperation;

...
public class AddOperation extends SCMMultiFileOperation
{
  public SCMControlItem getControlItem()
  {
    SCMControlItemObject item = new SCMControlItemObject();

    item.setName("Add...");
    item.setMnemonic('A');
    item.setContextItem(true);

    return item;
  }
  ...
}

Back to top

Toggle Operations

Toggle operations must also implement the following methods together with getControlItem():

For more details on isEnabled(Boolean), see 'No File' Operations.

getToggleState() should return a value to state if your toggle operation is currently toggled on or off.

You should call toggle(Boolean) when a user requests a change in the state of the file. This Hint about operate() also applies to toggle(Boolean).

Back to top

'No File' Operations

Operations that do not apply to any files are the simplest to implement. For these types of operation, you need to implement two more methods together with getControlItem():

Use isEnabled(Boolean) to return a value to state if your intended operation is possible at this point. The provided Boolean parameter, control, is the same as the value of isSourceControlEnabled() on your SCMClient implementation. For more details, see Advanced Features.

operate() is where you carry out the operation, so add your code here. If your operation fails, you can also throw an oracle.ide.scm.error.SCMException here. JDeveloper displays the exception message to the user in an alert dialog.

Hint: operate() is called on a different thread to the AWT event thread, so you can safely perform CPU intensive tasks in this method without blocking requests to the JDeveloper IDE to repaint the screen. However, be careful of thread safety issues when dealing with Swing components. If you call a method that might affect a Swing component, you should use the SwingUtilities.invokeLater() construct. 


import oracle.ide.scm.op.SCMNoFileOperation;
import oracle.ide.scm.error.SCMException;

...
public class ConnectOperation extends SCMNoFileOperation
{
  ...
  public Boolean isEnabled( Boolean scmEnabled )
  {
    return !m_client.isConnected();
  }

  public void operate() throws SCMException
  {
    m_client.setConnected( true );

  }
  ...
}

Back to top

Single File Operations

Operations that only apply to one file at a time must also implement the following methods together with getControlItem():

Use execute(SCMFile, SCMOptions) to carry out the operation. The SCMOptions argument is null unless you provide a dialog specification with an options customizer.

filter(SCMFile) determines which files are valid for this operation, which involves checking the state of the file using SCMFile.getStatus() and deciding if that state is valid for the operation.

getDialogSpecification() allows you to use the pre-defined confirmation dialog to retrieve the options available for the operation. You can safely return null for this method, which means JDeveloper does not display a dialog.

For more details on using an options customizer or dialog specifications, see Advanced Features.

Back to top

Multi File Operations

The SCM Framework enables you to perform operations on more than one selected file in the System Navigator. You can also perform a recursive operation on all the files in a project, package or any other container in the System Navigator at the same time.

To use this functionality, your operation must subclass SCMMultiFileOperation. Your operations must also implement the following methods together with getControlItem():

Use execute(Iterator, SCMOptions) to carry out the operation. The supplied Iterator provides access to SCMFile instances for each file on which you want to perform the operation. The SCMOptions argument is unless you provide a dialog specification with an options customizer.

For more details on filter(SCMFile) and getDialogSpecification(), see Single File Operations.

			
Import oracle.ide.scm.SCMOptions;
import oracle.ide.scm.SCMFile;
import oracle.ide.scm.op.SCMMultiFileOperation;
import oracle.ide.scm.error.SCMException;
import oracle.ide.scm.util.SCMVersionFileStatus;

...

public CheckInOperation extends SCMMultiFileOperation
{
  ...
  public void execute( Iterator i, SCMOptions options )
    throws SCMException
  {
    while ( i.hasNext() )
    {
      // BAD implementation, don't use this in real life!!
      SCMFile file = (SCMFile)i.next();
      URL u = file.getURL();
      URLFileSystem.setReadOnly( u, true );
    }
  }

  public Boolean filter( SCMFile file ) throws SCMException
  {
    // The only files that can be checked in are checked out files.
    return (file.getStatus() == SCMVersionFileStatus.STATUS_CHECKED_OUT);
  }
  ...
}

Hint: If you want to implement operations that run external processes (e.g. cvs.exe), consider using the SCMShellRunner utility.

Back to top

ACME VCS Sample

The sample file ACMEVCSClient.java demonstrates how to implement operations.

For more details on ACME VCS, see Introduction.

Back to top

Contents Previous Next