
Contents	Previous	Next

Utilities

This section gives an overview of the utilities that the SCM Framework provides to help you write source code control extensions:

Options Customizer for Comments
Shell Runner
SCM Utility Set
Operating System
Assertions and Error Reporting
Simple Client Superclass
IDE Node Commands
Environment Variables
File Status Constants

Options Customizer for Comments

This utility enables users to enter comments when taking any action, e.g. a check in or checkout and is supplied 'ready-to-use' in the SCM Framework. The Options Customizer can also reference your own customizer, presenting the user with a combined set of options. To use the Options Customizer, create an instance of oracle.ide.scm.util.SCMCommentsOptionsCustomizer as required and return it from getOptionsCustomizer() in an operation's dialog specification.

When the Options Customizer is used, the constant SCMCommentsOptionsCustomizer.KEY_COMMENT records the user's comments.

For more details on the Options Customizer, see Advanced Features.

Shell Runner

This utility is valuable if your source code control system is command-line based. Shell Runner provides a wrapper around the J2SE Runtime.exec() API for invoking external commands. We strongly recommend you use Shell Runner for invoking external commands to run your operations, as it works around several known issues and bugs with Runtime.exec(). In particular, Shell Runner:

launches an external command on Windows in the context of a shell and prevents a console window appearing for each process
monitors output and error streams of an external command as separate threads to prevent blocking issues due to buffer overruns

To use Shell Runner, first create an instance of oracle.ide.scm.util.SCMShellRunner and configure it to run the required command. You can define the command and any relevant environment variables and working directories. You can also create objects to monitor the output streams and provide a time-out for process activity. There are a number of types of stream monitor objects to choose from to find the most suitable for your needs. For more details, see the Shell Runner JavaDoc.

When your Shell Runner instance is ready, call exec() to run the command and return an object to represent the created process. Finally, invoke waitFor() if you need to wait for the command to finish before continuing. This provides a process exit code and buffered output for the command when the process is complete or if there is an error:

import oracle.ide.scm.util.runner.SCMShellRunner;
import oracle.ide.scm.util.runner.SCMProcess;
import oracle.ide.scm.util.runner.SCMLineStreamMonitor;

...
SCMShellRunner runner = new SCMShellRunner();

runner.setCommand( new String[] { "acmevcs", "-version" } );

// Set the timeout in milliseconds; ten seconds.
runner.setTimeout( 10000 );

runner.addOutputMonitor(new SCMLineStreamMonitor()
{
  protected final void streamLine(String line, SCMProcess process)
  {
    ACMELogWriter.getWriter().writeln( line );
  }
});

// Run the command and block while waiting for the process.
SCMProcess process = runner.exec().waitFor();

if ( process.getExitCode().intValue() == 0 )
{
  System.out.println( "Version is " + process.getOutputText() );
}
else
{
  System.out.println( "Something went wrong!" );
  System.out.println( process.getErrorText() );
}

Note: JDeveloper's existing support for CVS and ClearCase uses Shell Runner.

SCM Utility Set

The SCMUtilitySet utility provides the following useful methods for you to use:

Utility	Description
`createLogger()`	Creates a log window in the JDeveloper IDE to 'pipe out', e.g. commands from your source code control system.
`saveFiles()`	Saves all the modified files in a particular directory.
`showTextDialog()`	Shows a simple dialog containing some multi-line text, e.g. to show the user output from your source code control system.
`showTextWindow()`	Shows an non-editable editor window (MDI client window) in the JDeveloper IDE containing some specific text.

You can obtain an instance of oracle.ide.scm.env.SCMUtilitySet using the SCMSystem.getEnvironment().getUtils() API. For more details on SCMUtilitySet , see its JavaDoc.

Operating System

The oracle.ide.scm.util.SCMOperatingSystem utility determines on which operating system JDeveloper is running. Some source code control systems are sensitive to operating system specific issues, so you can use this utility to customize your extension at runtime to workaround any such issues.

Assertions and Error Reporting

To handle unexpected errors, use the static methods of oracle.ide.scm.util.SCMAssert. This utility gives you a standard way of dealing with serious exceptions in addition to handling the expected source code control extension exceptions described in Throwing and Handling Exceptions. Like these expected exceptions, you can also display further information about the error to the user. The profile of this class is almost identical to oracle.ide.util.Assert, but you should use SCMAssert instead:

import oracle.ide.scm.util.SCMAssert;

...
private static Map s_connections = new HashMap();

...
private static ACMEConnection getConnection(Object id)
{
  SCMAssert.precondition( id != null );

  ACMEConnection connection = (ACMEConnection)s_connections.get( id );
  SCMAssert.check( connection != null && connection.getId() == id );

  return connection;
}

Important: Assertion checking and messages in oracle.ide.scm.util.SCMAssert are not enabled by default, but you can enable them using SCMAssert.setEnabled(boolean). Users can also enable this functionality by running JDeveloper with a specific VM option. To set this option, users edit the jev.conf file in %JDEV_HOME%/jdev/bin and enter the following line: AddVMOption -Dide.SCMAssertCheckingEnabled=true.

Hint: We advise that you frequently check states using SCMAssert. This enables you to trap any problems occurring in your code as effectively as possible.

Simple Client Superclass

The class oracle.ide.scm.util.SCMSimpleClient is an abstraction of the SCM Framework with inherited menus and logging. A complete example of the code used is included in the JavaDoc.

If you only want to integrate basic source code control functionality, you can use the class oracle.ide.scm.util.SCMSimpleClient instead of this full SCM Framework. However, if you want to integrate a source code control system more tightly, this class may prove inflexible and not give all the necessary functionality. In these cases, you should consider using the full SCM Framework described in this guide.

IDE Node Commands

The class oracle.ide.scm.util.SCMIdeCommand ensures that commands on nodes in the JDeveloper IDE run correctly and are executed safely on the AWT event dispatch thread. The important utility methods of this class are:

openWorkspaceNode(URL)
openProjectNode(URL)
openNode(URL)

The SCM Framework helps to maintain nodes when an operation is complete by, e.g. closing the nodes for files that are deleted and reloading projects after they are modified.

Environment Variables

oracle.ide.scm.util.SCMEnvironmentVars supports obtaining environment variable values, so you can find the initial values of variables defined in the environment. This is useful if you want to integrate a source code control system with significant or many environment settings. To obtain the value of a variable, call getVariable(String) on a single instance of the utility. If you call getVariables(), you can see a map data structure containing all the default set variables.

Important: When you supply environment variables to Shell Runner, you override any definitions that are inherited from the environment of the current command. Therefore, you can use oracle.ide.scm.util.SCMEnvironmentVars to obtain those environment variables and configure them as necessary, then set the resulting variables on the shell runner used before executing the command.

File Status Constants

The class oracle.ide.scm.util.SCMVersionFileStatus defines various constants used to represent the state of a file relating to the source code control system used:

Constant	Description
`SCMVersionFileStatus.STATUS_UNVERSIONED`	File is not under version control. A user can add it as necessary.
`SCMVersionFileStatus.STATUS_VERSIONED`	File is under version control but is not yet checked in or checked out.
`SCMVersionFileStatus.STATUS_CHECKED_IN`	File is under version control and is checked in.
`SCMVersionFileStatus.STATUS_CHECKED_OUT`	File is under version control and is checked out.
`SCMVersionFileStatus.STATUS_UNRECOGNIZED`	File is not under version control and cannot be added.

If your source code control system uses any of these states, you can use this utility instead of implementing your own states. Obtain the state using getStatus(SCMFile) in oracle.ide.scm.SCMClient and use it as part of your logic to filter files when implementing file-based operations.

ACME VCS Sample

The sample file ACMEVCSClient.java demonstrates how to implement some of these utilities.

For more details on ACME VCS, see Introduction.


Contents	Previous	Next