JDeveloper SCM API

oracle.ide.scm
Interface SCMClient

All Superinterfaces:
oracle.ide.addin.Addin
All Known Implementing Classes:
SCMClientAdapter

public interface SCMClient
extends oracle.ide.addin.Addin

Interface to the integrated source control extension, providing support for client version control operations throught the user environment.

Implementors are expected to supply certain information about the nature of the supported system and verify that it is both installed and ready. The client provider defines the complete function set, the members of which control the behaviour and presentation of available actions. In addition, clients must accord with the 'pluggable' nature of source control extensions by responding suitably to a notification of change in the environment's active client. This may involve establishing a server connection and initializing upon startup, to ready the client. Symmetrically, the severing of any connection and sensible cleanup should be performed when the client becomes inactive.

Provision of checkout lister, pseudo-filesystem and property customization implementations is optional. The methods responsible for these may safely return a null to the framework. A determined file status may also be null, since these values are predominantly for client information through the wrappers for their associated files.

For reasons of deployment and convenience, this class extends the common interface for environment extensions. As such, client classes must have a default constructor made publically available, ensure that the extension is correctly initialized before general operation, and veto inappropriately timed shutdown requests.


Method Summary
 void detectClient()
          Detects whether the client is both installed and usable.
 void finishClient()
          Performs cleanup after client use.
 SCMCheckoutLister getCheckoutLister()
          Gets the interface to factory methods for the client's list checkouts configuration and worker.
 SCMFileSystem getFileSystem()
          Gets the filesystem interface to the client.
 SCMOperationSet getOperations()
          Retrieves the operations, specifying the appearance and behaviour of source control client actions.
 SCMPropertyCustomizer getPropertyCustomizer()
          Requests a Properties-based (name & value) customizer object from the SCM client.
 java.lang.String getSCMName()
          Gets a user displayable name for the source control system this client represents.
 java.lang.String getSCMShortName()
          Gets a user displayable short name for the source control system this client represents.
 SCMFileStatus getStatus(SCMFile file)
          Finds the current SCM status of the given file.
 boolean isSourceControlEnabled()
          Asks whether source control is currently enabled.
 void prepareClient()
          Prepares the client for use.
 
Methods inherited from interface oracle.ide.addin.Addin
canShutdown, ideVersion, initialize, shutdown, version
 

Method Detail

detectClient

public void detectClient()
                  throws SCMException
Detects whether the client is both installed and usable.
Throws:
SCMException - if the client is absent or cannot be facilitated.

prepareClient

public void prepareClient()
                   throws SCMException
Prepares the client for use. This method is invoked when the registered client has become the current selection, and must be ready to respond to operation requests.
Throws:
SCMException - if an error occurs in preparing the client for use.

getSCMName

public java.lang.String getSCMName()
Gets a user displayable name for the source control system this client represents.
Returns:
a localized string that represents the name of the source control system this client is for.

getSCMShortName

public java.lang.String getSCMShortName()
Gets a user displayable short name for the source control system this client represents. This should be under 10 characters long, and is used to display the name of the client to the user when space is at a premium.
Returns:
a short localized string.

getOperations

public SCMOperationSet getOperations()
                              throws SCMException
Retrieves the operations, specifying the appearance and behaviour of source control client actions.
Returns:
a set of category-separated operations as defined by the client.
Throws:
SCMException - if a reflection problem occurs when instantiating an operation from a client-specified class.

getFileSystem

public SCMFileSystem getFileSystem()
Gets the filesystem interface to the client. This is the programmatic interface to common file-based commands which may affect file version histories and require SCM client intervention. Implementors of a such an interface may override the default filesystem adapter provided in the framework. Note: this is optional funtionality, which can be given for future operability within the IDE.
Returns:
the filesystem implementation for the client, or null.

getCheckoutLister

public SCMCheckoutLister getCheckoutLister()
Gets the interface to factory methods for the client's list checkouts configuration and worker. The checkout lister may control the structure and contents of the list within a dockable IDE frame.
Returns:
the extension's checkout lister, or null.

getPropertyCustomizer

public SCMPropertyCustomizer getPropertyCustomizer()
Requests a Properties-based (name & value) customizer object from the SCM client. This will be used in user property setting through an environment preferences interface.
Returns:
an implementation of SCMPropertyCustomizer or null, where no client properties need to be configured

getStatus

public SCMFileStatus getStatus(SCMFile file)
                        throws SCMException

Finds the current SCM status of the given file. The returned status object should be a status constant that can be recognised by the operations of the extension. The standard status implementation is given by SCMVersionFileStatus, but this in no way prohibits more suitable custom constants from being used. Please note that an exception should be thrown only as a 'worst case', where the client cannot perform the query. If the given file is not controlled by the client, a suitable status should be returned.

This method may be called from many threads simultaneously. Ensure that your implementation is safe under these circumstances. The status call is also performance-critical, so attempt to return as soon as possible.

Parameters:
SCMFile - the file for which status information should be retrieved
Returns:
a representation for the found status of the file. Return null from this method only if it can be handled by the client extension's operations (status access through files).
Throws:
SCMException - if the client is unable to determine the file status.

isSourceControlEnabled

public boolean isSourceControlEnabled()
Asks whether source control is currently enabled. For example, whether a connection is open to the SCM system if required.
Returns:
a verdict on whether source control is enabled and operation-ready.

finishClient

public void finishClient()
                  throws SCMException
Performs cleanup after client use. This method is invoked when the registered client has been deselected, and any temporary cache or SCM connection should be finalized.
Throws:
SCMException - if an error occurs in finishing the client session.

Copyright © 2002 Oracle Corporation