SOA Assembly Framework Core Documentation

SAF Core API [Overview]

The SOA Assembly Framework (SAF) Core contribution provides an integration point between Eclipse-based tooling (such as editors and builders) and SCA model extension providers. Tooling can call the SAF Core API to accomplish various SCA artifact-related tasks without knowledge of specific artifact implementations, their providers, or their structure. Likewise, SCA model extension providers can make their SCA model extensions available to users of Eclipse-based tooling by supplying code, termed SCA extension handlers, which support a variety of SCA artifact-related operations. The result is that tooling can allow an end user to create and edit various types of SCA components, entry points, external services, and interfaces that the tooling does not need to understand, using code developed by different groups who have expertise in different areas.

In this document, references to types or methods in the Java API are enclosed by fixed-width fonts (like this) and references to elements in the schemas are enclosed in angle brackets(<like this />).

ISAFManager Interface

To execute a given operation on an SCA component, entry point, external service, or interface the client must first obtain an instance of the corresponding handler. The org.eclipse.stp.core.saf.ISAFManager interface provides various query methods that can be used to obtain a handler instance.

IHandler Interface Extensions

The IHandler interface defines the base API for all handlers contributed to the SAF Core. There are four specialized interfaces to handle each of the possible SCA model extensions.

  • IComponentHandler: Contributed to support operations on a new SCA implementation extension.
  • IEntryPointHandler: Contributed to support operations on an EntryPoint that supports the new SCA binding extension.
  • IExternalServiceHandler: Contributed to support operations on an ExternalService that supports the new SCA binding extension.
  • IInterfaceHandler: Contributed to support operations on a new SCA interface extension.

Context Object

The SAF Core implementation provides a context object, org.eclipse.stp.core.saf.Context, which can be used in various methods provided by the ISAFManager interface. If a context is defined for the given context key (carried in the Context object), the ISAFManager query output will be filtered to only contain the handlers supported for by the given context.

IUIContext Interface

This interface is meant to be implemented by clients calling the various handlers. This interface provides the UI shell, which may be required by a handler to display a dialog. An implementation of this interface is required in cases where a handler operation must interact with the user to complete.

SCA Extension Handlers [Top]

SCA extension providers can make their extensions available to users of SCA tooling by supplying handlers, which support a variety of operations.

SCA extension providers must contribute to the org.eclipse.stp.core.saf.handlers extension point, supplying one or more handler classes that, depending on the type of extension, implement one of the four specialized org.eclipse.stp.core.saf.handler.IHandler interfaces:

  • Component handlers manage a specific type of implementation.
  • EntryPoint handlers manage a specific type of binding in an entry point.
  • ExternalService handlers manage a specific type of binding in an external service.
  • Interface handlers manage a specific type of interface.

A handler provides a Service Provider Interface (SPI) that the framework uses to call the handler with various requests for creating and operating on an SCA extension object. The handler is identified by the SCA extension element name. The element names are interface.xxx, implementation.xxx, and binding.xxx. xxx can be a name that relates to the type of interface, implementation, or binding concerned.

The following example shows component, entry point, external service, and interface handler contributions:

<extension point=

"org.eclipse.stp.core.saf.handlers"

id=

"xyzHandlers"

name=

"XYZ handlers"

>

<componentHandler name=

"XYZ Component Handler"

description=

"Provides support for manipulating the XYZ implementation"

kind=

"implementation.xyz"

descriptiveKindName=

"xyz"

class=

"com.xyz.component.XYZComponentHandler"

/>

<entryPointHandler name=

"XYZ EntryPoint Binding Handler"

description=

"Provides support for manipulating the XYZ binding in an entry point"

kind=

"binding.xyz"

descriptiveKindName=

"xyz"

class=

"com.xyz.entrypoint.XYZBindingEntryPointHandler"

/>

<externalServiceHandler name=

"XYZ ExternalService Binding Handler"

description=

"Provides support for manipulating the XYZ binding in an external service"

kind=

"binding.xyz"

descriptiveKindName=

"xyz"

class=

"com.xyz.externalservice.XYZBindingExternalServiceHandler"

/>

<interfaceHandler name=

"XYZ Interface Handler"

description=

"Provides support for manipulating a XYZ interface"

kind=

"interface.xyz"

descriptiveKindName=

"xyz"

class=

"com.xyz.interface.XYZInterfaceHandler"

/>

</extension>

A handler instance can be obtained through various methods provided by the org.eclipse.stp.core.saf.ISAFManager interface.

Context and Context Extensions [Top]

The definition of a context allows for the restriction of SCA extension handler availability based on a given authoring criterion (i.e., context). This definition can be extended by specifying a context extension. These two concepts are described below.

Context Definition

The context extension point allows for the definition of a context that restricts the handlers that are available to clients of the framework working within the context. A context is generally associated with the root object being authored, usually a subsystem, module, or module fragment. It defines a set of constraints that apply to this root object. For example, if a context is defined for authoring a module of a given type, the component kind constraint could specify that only a subset of all contributed component handlers would be available.

A context can be defined by contributing to the org.eclipse.stp.core.saf.context extension point. The following is an example of a context definition:

<extension point=

"org.eclipse.stp.core.saf.context"

>

<context extensible=

"true"

>

<contextKey namespace=

"http://www.osoa.org/xmlns/sca/0.9"

rootType=

"module"

subType=

"someType"

/>

<componentKindConstraint includeKinds=

"true"

kinds=

"implementation.yyy"

/>

<entryPointKindConstraint includeKinds=

"true"

kinds=

"*"

/>

<externalServiceKindConstraint includeKinds=

"true"

kinds=

"*"

/>

</context>

</extension>

A context definition is used only when a matching org.eclipse.stp.core.saf.Context object is passed in to org.eclipse.stp.core.saf.ISAFManager when querying for handlers. The context object carries a key, which is matched to the corresponding context definition. If a match is found, the corresponding kind constraints are applied to the ISAFManager query results.

A context definition can also be specified to be extensible. In that case, a handler contributor can also extend an existing context to add the new handler to its definition by specifying a context extension.

Context Extension Definition

A context extension can be used to augment an existing context definition with a new handler contribution, as long as the context is extensible. If the context with matching context key element is not extensible, this contribution is ignored. In addition, the constraints specified by this extension are also ignored if they conflict with those specified in the context being extended.

A context extension can be defined by contributing to the org.eclipse.stp.core.saf.contextExtension extension point. The following is an example of a context extension definition that adds the implementation.xxx component kind to the context with a matching contextKey element:

<extension point=

"org.eclipse.stp.core.saf.contextExtension"

>

<contextExtension>

<contextKey namespace=

"http://www.osoa.org/xmlns/sca/0.9"

rootType=

"module"

subType=

"someType"

/>

<componentKindConstraint includeKinds=

"true"

kinds=

"implementation.xxx"

/>

</contextExtension>

</extension>

This documentation is maintained by Sebastian Carbajales (sebastia{at}ca.ibm.com). Questions or requests for clarifications should be made to the STP Developer mailing list (stp-dev@eclipse.org). See http://www.eclipse.org/mail/index_all.php for details on how to sign up.

Copyright (c) 2006 IBM Corporation. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html

[Overview] [Top]