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

All Superinterfaces:
IHandler
All Known Implementing Classes:
AbstractComponentHandler

public interface IComponentHandler
extends IHandler

This interface must be implemented by all component handlers. Most handlers should extend the abstract class AbstractComponentHandler which provides default behavior for a number of methods.


Method Summary
 boolean canAddReference()
          Queries if a reference can be added by the client to a component of the supported kind.
 boolean canAddService()
          Queries if a service can be added by the client to a component of the supported kind.
 boolean canCreateComponent()
          Queries if an unimplemented component of the kind supported by this handler can be created.
 boolean canCreateComponentFor(java.lang.Object implementationObj)
          Queries if a component of the kind supported by this handler can be created for the specified implementation file.
 boolean canCreateImplementation()
          Queries if implementation files can be created for components created by this component handler.
 boolean canSetImplementation()
          Queries if the component handler provides support for setting the implementation of a component using the method setImplementation().
 boolean canSetInterface()
          Queries if an interface can be set by the client in an existing service or reference contained by a component of the supported kind.
 org.eclipse.stp.core.sca.Component createComponent()
          Creates a component of the kind this handler is specialized for.
 org.eclipse.stp.core.sca.SCAObject[] createComponentFor(java.lang.Object implementationObj, org.eclipse.core.resources.IContainer container, IUIContext callback)
          Creates a component with an implementation based on the specified implementation model object.
 org.eclipse.wst.common.frameworks.datamodel.IDataModelOperation createImplementationFor(org.eclipse.stp.core.sca.Component theComponent, org.eclipse.core.resources.IContainer container, IUIContext callback)
          Creates an implementation file or files for the specified component based on the definition of the component.
 org.eclipse.core.resources.IFile[] getImplementationFor(org.eclipse.stp.core.sca.Component theComponent)
          Returns an array of implementation files associated with the given component.
 boolean isInterfaceKindSupported(IInterfaceHandler interfaceHandler, boolean service)
          Queries if a component of the kind supported by this handler supports interfaces of the kind specified by the given interface handler in its services or references.
 void open(org.eclipse.stp.core.sca.Component theComponent)
          This method opens a registered editor for the given component implementation type.
 org.eclipse.wst.common.frameworks.datamodel.IDataModelOperation resetKind(org.eclipse.stp.core.sca.Component theComponent)
          Changes the component to be unclassified by removing the implementation of the component or by creating an untyped AbstractImplementation.
 org.eclipse.wst.common.frameworks.datamodel.IDataModelOperation setImplementation(org.eclipse.stp.core.sca.Component component, java.lang.Object implementationObject, IUIContext callback)
          Sets the implementation of the component to the specified model object.
 org.eclipse.wst.common.frameworks.datamodel.IDataModelOperation setKind(org.eclipse.stp.core.sca.Component theComponent)
          Sets the component to be one of the specified kind.
 
Methods inherited from interface org.eclipse.stp.core.saf.handler.IHandler
getDescription, getDescriptiveKindName, getKind, getLargeIcon, getName, getSmallIcon
 

Method Detail

createComponent

public org.eclipse.stp.core.sca.Component createComponent()
                                                   throws SAFException
Creates a component of the kind this handler is specialized for.

Returns:
the new component
Throws:
SAFException - when a component cannot be created

canCreateComponent

public boolean canCreateComponent()
Queries if an unimplemented component of the kind supported by this handler can be created. Some component kinds may not be authored in a top-down scenario. In these cases, this method will return false. If this method returns true, the handler's createComponent() method may be called to create a component.

Returns:
true if the handler can create an unimplemented Component object; false otherwise

canCreateComponentFor

public boolean canCreateComponentFor(java.lang.Object implementationObj)
Queries if a component of the kind supported by this handler can be created for the specified implementation file. If this method returns true, the handler's createComponentFor(Object,IContainer,IUIContext) method may be called to create a component for the file.

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

Parameters:
implementationObj - an object representing the implementation for a component
Returns:
true if the handler can create an Component object from the specified file; false otherwise

createComponentFor

public org.eclipse.stp.core.sca.SCAObject[] createComponentFor(java.lang.Object implementationObj,
                                                               org.eclipse.core.resources.IContainer container,
                                                               IUIContext callback)
                                                        throws SAFException,
                                                               java.lang.InterruptedException,
                                                               InvalidOperationException
Creates a component with an implementation based on the specified implementation model object. Optionally, this method may create other objects required to support the new component (such as entry points, other components, etc.). This method is not expected to associate a resource with the returned component or any of the supporting objects.

Parameters:
implementationObj - the object representing the implementation for the component
container - the IContainer that holds the module, subsystem, composite, etc. that will use the resulting component. The handler could use the container's location to generate relative file paths that it stores in the component (to reference the implementation file, for example) or use the location as a place for additional files that need to be generated.
callback - callback object that the handler can use to obtain additional information needed to create the component. Callers can pass in a null value.
Returns:
an array of SCAObject containing the new component and any other SCA objects generated by the handler to support the new component
Throws:
SAFException - an unexpected exception occurred
InvalidOperationException - a component cannot be created for the given implementation object
java.lang.InterruptedException - the caller did not provide a callback object needed by the handler, or the callback request was canceled or aborted

canCreateImplementation

public boolean canCreateImplementation()
Queries if implementation files can be created for components created by this component handler. A caller can use this method to distinguish fully functional component handlers from those that do not provide support for generating implementations for the components they create.

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

createImplementationFor

public org.eclipse.wst.common.frameworks.datamodel.IDataModelOperation createImplementationFor(org.eclipse.stp.core.sca.Component theComponent,
                                                                                               org.eclipse.core.resources.IContainer container,
                                                                                               IUIContext callback)
                                                                                        throws SAFException,
                                                                                               java.lang.InterruptedException,
                                                                                               InvalidOperationException
Creates an implementation file or files for the specified component based on the definition of the component. The handler is expected to update the implementation object in the component to reference the generated file or files, if necessary. The implementation file or files will be regenerated and replaced. User changes made to these files will be not be preserved.

This method should be aware that the implementation files it generates may replace some already being managed in a team environment.

Parameters:
theComponent - the component whose implementation is to be generated
container - the IContainer that holds the module, subsystem, composite, etc. that contains the given component. The handler could use the container's location to generate relative file paths that it stores in the component (to reference the implementation file, for example) or use the location as a place for additional files that need to be generated.
callback - callback object that the handler can use to obtain additional information needed to create the implementation files. Callers may pass in a null value.
Returns:
an IDataModelOperation instance that, once executed by the caller, creates the new implementation
Throws:
SAFException - an unexpected exception occurred
InvalidOperationException - an implementation cannot be created for the given component kind
java.lang.InterruptedException - the caller did not provide a callback object needed by the handler, or the callback request was canceled or aborted.

getImplementationFor

public org.eclipse.core.resources.IFile[] getImplementationFor(org.eclipse.stp.core.sca.Component theComponent)
                                                        throws SAFException
Returns an array of implementation files associated with the given component. The "primary" file should be the first element in the array.

Parameters:
theComponent - the component whose implementation files are returned
Returns:
an array of the associated implementation files
Throws:
SAFException - An error occurred finding the implementation files.

open

public void open(org.eclipse.stp.core.sca.Component theComponent)
          throws SAFException,
                 InvalidOperationException
This method opens a registered editor for the given component implementation type.

Parameters:
theComponent - the component whose implementation is to be opened
Throws:
SAFException - An unexpected exception occurred.
InvalidOperationException - The component's implementation cannot be opened.

canSetImplementation

public boolean canSetImplementation()
Queries if the component handler provides support for setting the implementation of a component using the method setImplementation(). This method should be called before calling setImplementation(). A caller can use this method to determine if the corresponding component handler implements the method setImplementation(). If this method returns false, neither method should be called.

Returns:
true if the handler supports the calling of setImplementation(); false otherwise

setImplementation

public org.eclipse.wst.common.frameworks.datamodel.IDataModelOperation setImplementation(org.eclipse.stp.core.sca.Component component,
                                                                                         java.lang.Object implementationObject,
                                                                                         IUIContext callback)
                                                                                  throws SAFException,
                                                                                         java.lang.InterruptedException,
                                                                                         InvalidOperationException
Sets the implementation of the component to the specified model object. Generally, existing interfaces and references will be preserved. No clean-up is done on existing implementation files.

Parameters:
component - the component being modified
implementationObject - the object to be used to implement the specified component
callback - callback object that the component handler can use to obtain additional information needed to create the component; can be left null, although some calls may fail
Returns:
an IDataModelOperation instance that, once executed by the caller, sets the implementation
Throws:
SAFException - An unexpected exception occurred.
InvalidOperationException - The implementation cannot be set for the given component.
java.lang.InterruptedException - A callback method throws an exception, or the user cancels the callback conversation.

isInterfaceKindSupported

public boolean isInterfaceKindSupported(IInterfaceHandler interfaceHandler,
                                        boolean service)
                                 throws SAFException
Queries if a component of the kind supported by this handler supports interfaces of the kind specified by the given interface handler in its services or references.

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.
service - flag indicating if the query applies to the services of the component or its references. The values ISAFManager.SERVICE and ISAFManager.REFERENCE can be used for improved code readability.
Returns:
true if the component supports the specified use of the interface kind; false otherwise
Throws:
SAFException - An unexpected exception occurred in the handler.

canAddReference

public boolean canAddReference()
Queries if a reference can be added by the client to a component of the supported kind.

Returns:
true if the client is allowed to add a reference object; false otherwise

canAddService

public boolean canAddService()
Queries if a service can be added by the client to a component of the supported kind.

Returns:
true if the client is allowed to add a service object; false otherwise

canSetInterface

public boolean canSetInterface()
Queries if an interface can be set by the client in an existing service or reference contained by a component of the supported kind.

Returns:
true if the client is allowed to set the interface on a given service or reference object; false otherwise

setKind

public org.eclipse.wst.common.frameworks.datamodel.IDataModelOperation setKind(org.eclipse.stp.core.sca.Component theComponent)
                                                                        throws SAFException,
                                                                               InvalidOperationException
Sets the component to be one of the specified kind. Generally, existing interfaces and references will be preserved. The component must not already be typed (that is, it must contain an untyped AbstractImplementation or no implementation at all). Call resetKind(Component) beforehand, if necessary. If the kind cannot be set for the given component (perhaps due to unsupported interface kinds already set), an error message will be displayed through the given callback object.

Parameters:
theComponent - the component being modified
Returns:
an IDataModelOperation instance that, once executed by the caller, sets the component kind
Throws:
SAFException - No handler for the specified kind is found, or the type is not supported.
InvalidOperationException - The component kind cannot be set for the given component.

resetKind

public org.eclipse.wst.common.frameworks.datamodel.IDataModelOperation resetKind(org.eclipse.stp.core.sca.Component theComponent)
                                                                          throws SAFException,
                                                                                 InvalidOperationException
Changes the component to be unclassified by removing the implementation of the component or by creating an untyped AbstractImplementation. Generally, existing interfaces and references will be preserved. No clean-up is done on existing implementation files. If the component is already unclassified, this method performs no work.

Parameters:
theComponent - the component being modified
Returns:
an IDataModelOperation instance that, once executed by the caller, resets the component kind
Throws:
SAFException - No handler for the specified kind is found, or the handler throws an exception.
InvalidOperationException - The component kind cannot be reset for the given component.