org.eclipse.stp.core.saf.handler
Interface IExternalServiceHandler

All Superinterfaces:
IHandler
All Known Implementing Classes:
AbstractExternalServiceHandler

public interface IExternalServiceHandler
extends IHandler

This interface must be implemented by all external service handlers. Most handlers should extend the abstract class AbstractExternalServiceHandler which provides certain convenient methods.


Method Summary
 boolean canCreateExternalServiceBinding()
          Queries if the external service handler provides support for creating an external service binding using the method createExternalServiceBindingFor().
 boolean canCreateExternalServiceFor(java.lang.Object service)
          Queries if an external service of the kind supported by this handler can be created for the specified model object.
 boolean canCreateManyExternalServiceBindings()
          Queries if the external service handler provides support for creating more than one binding instance for an external service.
 org.eclipse.wst.common.frameworks.datamodel.IDataModelOperation createExternalServiceBindingFor(org.eclipse.stp.core.sca.ExternalService theExternalService, IUIContext callback)
          Adds a binding of the kind supported by this handler to the specified ExternalService object, based on the specified service file and the interfaces in the external service definition.
 org.eclipse.stp.core.sca.SCAObject[] createExternalServiceFor(java.lang.Object service, org.eclipse.core.resources.IContainer container, IUIContext callback)
          Creates an external service with a binding of the kind supported by this handler for the specified model object.
 boolean isInterfaceKindSupported(IInterfaceHandler interfaceHandler)
          Queries if an external service of the kind supported by this handler supports interfaces of the kind specified by the given interface handler in its interface set.
 org.eclipse.wst.common.frameworks.datamodel.IDataModelOperation removeKind(org.eclipse.stp.core.sca.ExternalService theExternalService)
          Removes a given binding kind from the external service.
 
Methods inherited from interface org.eclipse.stp.core.saf.handler.IHandler
getDescription, getDescriptiveKindName, getKind, getLargeIcon, getName, getSmallIcon
 

Method Detail

canCreateExternalServiceFor

public boolean canCreateExternalServiceFor(java.lang.Object service)
Queries if an external service of the kind supported by this handler can be created for the specified model object. If this method returns true, the handler's createExternalServiceFor(Object,IContainer,IUIContext) method may be called to create an external service for the model object.

This method should be quick to execute, because it may be called to populate a context menu or a user dialog.

Parameters:
service - an object representing a service that may be imported
Returns:
true if the handler can create an ExternalService object from the specified model object; false otherwise

createExternalServiceFor

public org.eclipse.stp.core.sca.SCAObject[] createExternalServiceFor(java.lang.Object service,
                                                                     org.eclipse.core.resources.IContainer container,
                                                                     IUIContext callback)
                                                              throws SAFException,
                                                                     java.lang.InterruptedException,
                                                                     InvalidOperationException
Creates an external service with a binding of the kind supported by this handler for the specified model object. All interfaces of the service file are imported. To import specific interfaces, call createExternalServiceBindingFor(ExternalService, IUIContext) instead. Optionally, this method may create other objects required to support the new external service (such as a component). This method is not expected to associate a resource with the returned ExternalService or supporting object.

Parameters:
service - an object representing a service that may be imported
container - the container that holds the module, subsystem, composite, etc. that will use the external service object returned by this method. The handler could use its location as a base to place any binding-related files that need to be generated.
callback - callback object that the handler can use to obtain additional information needed to create the external service. Callers may pass in a null value.
Returns:
an array of SCAObject containing the new external service and any other SCA objects generated by the handler to support the new external service
Throws:
SAFException - An unexpected exception occurred.
InvalidOperationException - An external service cannot be created from the given service object.
java.lang.InterruptedException - The caller did not provide a callback object needed by the handler, or the callback request was canceled or aborted.

canCreateExternalServiceBinding

public boolean canCreateExternalServiceBinding()
Queries if the external service handler provides support for creating an external service binding using the method createExternalServiceBindingFor().

Returns:
true if support is provided for creating a binding; false otherwise

canCreateManyExternalServiceBindings

public boolean canCreateManyExternalServiceBindings()
Queries if the external service handler provides support for creating more than one binding instance for an external service.

Returns:
true if support is provided for creating more than one binding of the supported kind; false otherwise

createExternalServiceBindingFor

public org.eclipse.wst.common.frameworks.datamodel.IDataModelOperation createExternalServiceBindingFor(org.eclipse.stp.core.sca.ExternalService theExternalService,
                                                                                                       IUIContext callback)
                                                                                                throws SAFException,
                                                                                                       java.lang.InterruptedException,
                                                                                                       InvalidOperationException
Adds a binding of the kind supported by this handler to the specified ExternalService object, based on the specified service file and the interfaces in the external service definition. The handler is expected to update the external service definition, if necessary. If the external service has an existing binding, the handler can add to or replace the binding. The handler can use the callback to query for more information from the user. If the binding requires associated files, this method should generate those files. In this case, this method should be aware that the files it generates may replace some already being managed in a team environment. The ExternalService object should have a resource associated with it. The handler can use this location to generate relative file references if needed or use the location for storing binding-related files that need to be generated. The resource can be retrieved by casting the ExternalService object to an EObject and calling EObject.eResource().

Parameters:
theExternalService - an existing external service definition, which may contain interfaces and a binding
callback - callback object that the handler can use to obtain additional information needed to create the binding. Callers may pass in a null value.
Returns:
an IDataModelOperation instance that, once executed by the caller, creates the new external service binding
Throws:
SAFException - An unexpected exception occurred.
InvalidOperationException - A binding cannot be created for the given external service.
java.lang.InterruptedException - The caller did not provide a callback object needed by the handler, or the callback request was canceled or aborted.

isInterfaceKindSupported

public boolean isInterfaceKindSupported(IInterfaceHandler interfaceHandler)
                                 throws SAFException
Queries if an external service of the kind supported by this handler supports interfaces of the kind specified by the given interface handler in its interface set.

Parameters:
interfaceHandler - the interface handler that will be used to manipulate the interface. The implementation of this method can obtain the interface kind by invoking IHandler.getKind() when performing the evaluation.
Returns:
true if the external service supports interfaces of the specified interface kind; false otherwise
Throws:
SAFException - An unexpected exception occurred in the handler.

removeKind

public org.eclipse.wst.common.frameworks.datamodel.IDataModelOperation removeKind(org.eclipse.stp.core.sca.ExternalService theExternalService)
                                                                           throws SAFException,
                                                                                  InvalidOperationException
Removes a given binding kind from the external service. Generally, existing interfaces will be preserved. No clean-up is done on existing binding-related files. If the external service does not contain the given binding type, this method performs no work.

Parameters:
theExternalService - the external service being modified
Returns:
an IDataModelOperation instance that, once executed by the caller, resets the extenal service point kind
Throws:
SAFException - No handler for the specified kind is found, or the handler throws an exception.
InvalidOperationException - The external service kind cannot be removed.