Writing own Binding Type for Tuscany 2.*

[Sebastian Schleicher <se...@googlemail.com>]

Hi,

My friends and I are trying to implement an own binding type for Tuscany 2.0
M5 but have no
idea what's required, even after reading through loads of documentation and
presentation papers.

Could anybody hand us over a skeleton of empty classes and OSGi delcarations
containing everything
needed to start working? In fact, we don't really know where to start. We
even don't really know how
the binding type will be plugged into the OSGi of tuscany so that it can be
used within the composite files.

A tutorial, example files or an explanation. We'd be thankful for all
support.



Thank you so far,


Sebastian

Re: Writing own Binding Type for Tuscany 2.*

[ant elder <an...@gmail.com>]

On Wed, Sep 1, 2010 at 3:49 PM, Simon Laws <si...@googlemail.com> wrote:
> On Wed, Sep 1, 2010 at 1:19 PM, Sebastian Schleicher
> <se...@googlemail.com> wrote:
>> Hi,
>>
>> My friends and I are trying to implement an own binding type for Tuscany 2.0
>> M5 but have no
>> idea what's required, even after reading through loads of documentation and
>> presentation papers.
>>
>> Could anybody hand us over a skeleton of empty classes and OSGi delcarations
>> containing everything
>> needed to start working? In fact, we don't really know where to start. We
>> even don't really know how
>> the binding type will be plugged into the OSGi of tuscany so that it can be
>> used within the composite files.
>>
>> A tutorial, example files or an explanation. We'd be thankful for all
>> support.
>>
>>
>>
>> Thank you so far,
>>
>>
>> Sebastian
>>
>
> Hi Sebastian
>
> We haven't ported the sample binding extension (binding-echo) across
> from 1.x yet hence there is a gap in our sample list. Please raise a
> JIRA asking for a binding extension sample to be added and we'll see
> what we can do.
>
> The 2.x docs are also deficient at the moment also. Raymond did make
> some slides about extensions in general [1]. And there are some notes
> about how to do things in an OSGi friendly way linked from the
> "Development Guides" page [2]. Having said this the Tuscany runtime
> runs in both JSE and OSGi environments so there is very little that's
> OSGi specific about Tuscany bindings. You'll note that we provide a
> manually generated manifest file with each extension Jar so that they
> can be loaded into OSGi. Also some bindings use some classloader
> tricks to make the integration with the underlying technology work in
> an OSGi environment but I suggest you cross that bridge if you happen
> to come to it.
>
> Bindings are fairly straightforward. If you imagine that the binding
> runtime sits between the transport protocol and the Tuscany message
> chain then you utlimately need to provide a binding specific invoker
> on the reference side and a listener on the service side. If you look
> toward the bottom of the runtime overview page [3] you can see where
> the binding runtime fits in the grand scheme of things.
>
> There is more work to do to integrate a binding into the Tuscany
> runtime however. Here's a very brief overview.
>
> Primarily a binding has to provide an implementation of a set of
> Tuscany extension points and then register these extension point
> implementations using entries in files that are found under
> META-INF/services. The best way to get started is to base your new
> binding on an existing binding.
>
> For example, take a look at a fairly simple binding such as
> binding-jsonrpc. This allows component services and references to
> communicate using the JSONRPC protocol, which is basically JSON over
> HTTP with a few twists. The binding extension is made up of two maven
> modules in the code base
>
> binding-jsonrpc
> binding-jsonrpc-runtime
>
> (I'm ignoring binding-jsonrpc-js-dojo here to keep things simple)
>
> The jsonrpc binding could appear in a composite file in the following way.
>
> <composite ...>
>  <component name="ComponentA">
>      <implementation ..../>
>      <service name="ComponentAService">
>          <binding-jsonrpc
> uri="http://localhost:8080/Service/ComponentAService"/>
>      </service>
>  </component>
>  <component name="ComponentB">
>      <implementation ..../>
>      <reference name="componentAServiceReference">
>          <binding-jsonrpc
> uri="http://localhost:8080/Service/ComponentAService"/>
>      </service>
>  </component>
> </composite>
>
> The <binding-jsonrpc/> element has to be read in and modeled in
> memory. This is what the binding-jsonrpc module does. If you look in
> the META-INF/services information you'll note that this binding uses a
> DefaultBeanModelProcessor to read, write and resolve the binding
> model. If your new binding has complex configuration you may need to
> write your own processor implementation.
>
> Once the Tuscany model of the composite application has the
> binding-jsonrpc model read into it the runtime will try and create
> runtime artifacts for the binding (invokers for references and
> listeners for services). This is what the binding-jsonrpc-runtime
> provides. You'll note that there are reference and service provider
> classes in the module (again registered via META-INF/services). The
> providers let a binding extension create the binding specific invokers
> and listeners in a binding specific way.
>
> Given the lack of detailed documentation for 2.x at the moment a good
> way to learn is to pick a simple example, put some breakpoints in the
> various binding classes and run it in the debugger. For example, the
> module binding-jsonrpc-runtime module has some simple JUnit tests that
> run the jsonrpc binding that you could look at.
>
> [1] http://tuscany.apache.org/documentation-2x/development-guides.data/Tuscany%202.x%20Extensibility%20and%20SPIs.ppt
> [2] http://tuscany.apache.org/documentation-2x/development-guides.html
> [3] http://tuscany.apache.org/documentation-2x/sca-java-runtime-overview.html
>
> I realize that this is only the briefest of overviews but I hope it
> gets you started. Don't hesitate to ask more questions.
>
> Regards
>
> Simon
>

I've committed an example of a simplistic binding at:
https://svn.apache.org/repos/asf/tuscany/sca-java-2.x/contrib/modules/binding-foo-runtime/

Thats about as simple as it could be with all unnecessary code
stripped out so you should be able to see the main things you need. If
you can say a little more about what the binding you want to write
does we might be able to help you with adding more relevant code to
that example, eg does it need to use http and use the Tuscany HTTP
host framework?, or does it have any data binding requirements?

   ...ant

Re: Writing own Binding Type for Tuscany 2.*

[Simon Laws <si...@googlemail.com>]

On Wed, Sep 1, 2010 at 1:19 PM, Sebastian Schleicher
<se...@googlemail.com> wrote:
> Hi,
>
> My friends and I are trying to implement an own binding type for Tuscany 2.0
> M5 but have no
> idea what's required, even after reading through loads of documentation and
> presentation papers.
>
> Could anybody hand us over a skeleton of empty classes and OSGi delcarations
> containing everything
> needed to start working? In fact, we don't really know where to start. We
> even don't really know how
> the binding type will be plugged into the OSGi of tuscany so that it can be
> used within the composite files.
>
> A tutorial, example files or an explanation. We'd be thankful for all
> support.
>
>
>
> Thank you so far,
>
>
> Sebastian
>

Hi Sebastian

We haven't ported the sample binding extension (binding-echo) across
from 1.x yet hence there is a gap in our sample list. Please raise a
JIRA asking for a binding extension sample to be added and we'll see
what we can do.

The 2.x docs are also deficient at the moment also. Raymond did make
some slides about extensions in general [1]. And there are some notes
about how to do things in an OSGi friendly way linked from the
"Development Guides" page [2]. Having said this the Tuscany runtime
runs in both JSE and OSGi environments so there is very little that's
OSGi specific about Tuscany bindings. You'll note that we provide a
manually generated manifest file with each extension Jar so that they
can be loaded into OSGi. Also some bindings use some classloader
tricks to make the integration with the underlying technology work in
an OSGi environment but I suggest you cross that bridge if you happen
to come to it.

Bindings are fairly straightforward. If you imagine that the binding
runtime sits between the transport protocol and the Tuscany message
chain then you utlimately need to provide a binding specific invoker
on the reference side and a listener on the service side. If you look
toward the bottom of the runtime overview page [3] you can see where
the binding runtime fits in the grand scheme of things.

There is more work to do to integrate a binding into the Tuscany
runtime however. Here's a very brief overview.

Primarily a binding has to provide an implementation of a set of
Tuscany extension points and then register these extension point
implementations using entries in files that are found under
META-INF/services. The best way to get started is to base your new
binding on an existing binding.

For example, take a look at a fairly simple binding such as
binding-jsonrpc. This allows component services and references to
communicate using the JSONRPC protocol, which is basically JSON over
HTTP with a few twists. The binding extension is made up of two maven
modules in the code base

binding-jsonrpc
binding-jsonrpc-runtime

(I'm ignoring binding-jsonrpc-js-dojo here to keep things simple)

The jsonrpc binding could appear in a composite file in the following way.

<composite ...>
  <component name="ComponentA">
      <implementation ..../>
      <service name="ComponentAService">
          <binding-jsonrpc
uri="http://localhost:8080/Service/ComponentAService"/>
      </service>
  </component>
  <component name="ComponentB">
      <implementation ..../>
      <reference name="componentAServiceReference">
          <binding-jsonrpc
uri="http://localhost:8080/Service/ComponentAService"/>
      </service>
  </component>
</composite>

The <binding-jsonrpc/> element has to be read in and modeled in
memory. This is what the binding-jsonrpc module does. If you look in
the META-INF/services information you'll note that this binding uses a
DefaultBeanModelProcessor to read, write and resolve the binding
model. If your new binding has complex configuration you may need to
write your own processor implementation.

Once the Tuscany model of the composite application has the
binding-jsonrpc model read into it the runtime will try and create
runtime artifacts for the binding (invokers for references and
listeners for services). This is what the binding-jsonrpc-runtime
provides. You'll note that there are reference and service provider
classes in the module (again registered via META-INF/services). The
providers let a binding extension create the binding specific invokers
and listeners in a binding specific way.

Given the lack of detailed documentation for 2.x at the moment a good
way to learn is to pick a simple example, put some breakpoints in the
various binding classes and run it in the debugger. For example, the
module binding-jsonrpc-runtime module has some simple JUnit tests that
run the jsonrpc binding that you could look at.

[1] http://tuscany.apache.org/documentation-2x/development-guides.data/Tuscany%202.x%20Extensibility%20and%20SPIs.ppt
[2] http://tuscany.apache.org/documentation-2x/development-guides.html
[3] http://tuscany.apache.org/documentation-2x/sca-java-runtime-overview.html

I realize that this is only the briefest of overviews but I hope it
gets you started. Don't hesitate to ask more questions.

Regards

Simon

-- 
Apache Tuscany committer: tuscany.apache.org
Co-author of a book about Tuscany and SCA: tuscanyinaction.com