intents.xml 5.45 KB
Newer Older
Nicolas Dolet's avatar
Nicolas Dolet committed
1
2
3
4
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter>
5
  <title>SCA intents with OW2 FraSCAti</title>
Nicolas Dolet's avatar
Nicolas Dolet committed
6

7
8
  <para>SCA intents can be used for non-functional concerns, such as
  transactions, debuging, etc.</para>
Nicolas Dolet's avatar
Nicolas Dolet committed
9
10

  <para>This chapter is organized as following: <xref
11
  linkend="debug-intent" /> illustrates how to use the debug intent of OW2
Nicolas Dolet's avatar
Nicolas Dolet committed
12
13
14
15
16
17
18
  FraSCAti and <xref linkend="implement-an-intent" /> explains how to create
  your own intent.</para>

  <xi:include href="../../debug/src/docbkx/debug-intent.xml"
              xmlns:xi="http://www.w3.org/2001/XInclude" />

  <section id="implement-an-intent">
19
    <title>SCA intent</title>
Nicolas Dolet's avatar
Nicolas Dolet committed
20

21
22
    <para>Implementing new SCA intent for FraSCAti can be easily done by
    following these steps:</para>
Nicolas Dolet's avatar
Nicolas Dolet committed
23
24
25
26

    <section>
      <title>SCA definition</title>

27
28
29
      <para>SCA intents for OW2 FraSCAti are implemented as SCA composites.
      Assuming that you want to create an intent named <code>foo</code>, you
      have first to write a <code>foo.composite</code> file, that promotes the
Nicolas Dolet's avatar
Nicolas Dolet committed
30
31
32
33
      intent service of the primitive SCA component inside.</para>

      <programlisting>&lt;composite xmlns="http://www.osoa.org/xmlns/sca/1.0" name="foo"&gt;
  
34
  &lt;service name="intent" promote="primitiveIntentHandler/fooIntentService"/&gt;
Nicolas Dolet's avatar
Nicolas Dolet committed
35
36
37
38
39
40
41
42
43
44
  
  &lt;component name="primitiveIntentHandler"&gt;
     &lt;service name="fooIntentService"&gt;
       &lt;interface.java interface="org.ow2.frascati.tinfi.control.intent.IntentHandler"/&gt;
     &lt;/service&gt;
    &lt;implementation.java class="org.ow2.frascati.tutorial.FooIntentHandlerImpl"/&gt;
  &lt;/component&gt;
  
&lt;/composite&gt;</programlisting>

45
46
47
48
49
50
51
52
53
      <para>The name of the service this composite must be <code>intent</code>
      and its Java interface must implement the <code>IntentHandler</code>
      Tinfi interface. Then, the Java implementation class of the primitive
      intent handler will implement this interface, as shown in next
      section.</para>

      <para>This is the minimum to do for creating an intent, but an intent
      composite can be much more complex (with several SCA components, other
      services and references to external services, etc.)</para>
Nicolas Dolet's avatar
Nicolas Dolet committed
54
55
56
57
58
59
    </section>

    <section>
      <title>Intent implementation</title>

      <para>The Java implementation of the handler must be a class that
60
      implement the <code>IntentHandler</code> Tinfi interface. Intent
Nicolas Dolet's avatar
Nicolas Dolet committed
61
62
63
64
65
66
67
68
69
70
71
      handlers are implemented in an <ulink
      url="http://en.wikipedia.org/wiki/Aspect-oriented_programming">AOP</ulink>
      way, with the invoke/proceed pattern. Then, implementing the intent
      handler means to add some non-functionnal code before and after the
      execution of the business code.</para>

      <programlisting>package org.ow2.frascati.tutorial;

import org.osoa.sca.annotations.Scope;

@Scope("COMPOSITE")
72
public class FooIntentHandler
Nicolas Dolet's avatar
Nicolas Dolet committed
73
74
75
76
77
78
79
80
81
82
83
  implements IntentHandler {

  // --------------------------------------------------------------------------
  // Implementation of the IntentHandler interface
  // --------------------------------------------------------------------------

  /**
   * @see org.ow2.frascati.tinfi.control.intent.IntentHandler#invoke(IntentJoinPoint)
   */
  public Object invoke(IntentJoinPoint ijp) throws Throwable {
    Object ret;
84
    <emphasis role="bold">//
Nicolas Dolet's avatar
Nicolas Dolet committed
85
    // PUT HERE CODE TO RUN BEFORE THE JOINPOINT PROCESSING
86
    //</emphasis>
Nicolas Dolet's avatar
Nicolas Dolet committed
87
    ret = ijp.proceed();
88
    <emphasis role="bold">//
Nicolas Dolet's avatar
Nicolas Dolet committed
89
    // PUT HERE CODE TO RUN AFTER THE JOINPOINT PROCESSING
90
    //</emphasis>
Nicolas Dolet's avatar
Nicolas Dolet committed
91
92
93
94
95
96
    return ret;
  }
}</programlisting>
    </section>

    <section>
97
      <title>Use your SCA intent</title>
Nicolas Dolet's avatar
Nicolas Dolet committed
98
99
100
101
102
103
104
105

      <para>When your intent is implemented, the only thing you have to do for
      using it is to set its name as a requires on any component, service or
      reference of an SCA definition. With the foo.composite intent previously
      described, a usage can be:</para>

      <programlisting>&lt;composite xmlns="http://www.osoa.org/xmlns/sca/1.0" &gt;
  
106
  &lt;component name="myComponent" <emphasis role="bold">requires="foo"</emphasis>&gt;
Nicolas Dolet's avatar
Nicolas Dolet committed
107
108
109
110
    ...
  &lt;/component&gt;

&lt;/composite&gt;</programlisting>
Christophe Demarey's avatar
Christophe Demarey committed
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

      <para>In this case, the <emphasis>foo</emphasis> intent is applied on
      all services and interfaces of the component
      <emphasis>myComponent</emphasis>.</para>

      <para>You can also define an intent on one or several
      service(s)/reference(s) as following:</para>

      <programlisting>&lt;composite xmlns="http://www.osoa.org/xmlns/sca/1.0" &gt;
  
  &lt;component name="myComponent"&gt;
    &lt;service name="s1" <emphasis role="bold">requires="foo"</emphasis>&gt;
      ...
    &lt;/service&gt;
    &lt;service name="s2"&gt;
      ...
    &lt;/service&gt;
    &lt;reference name="r1" <emphasis role="bold">requires="foo"</emphasis>&gt;
      ...
    &lt;/reference&gt;
    ...
  &lt;/component&gt;

&lt;/composite&gt;</programlisting>

      <para>Here, the <emphasis>foo</emphasis> intent wil only be applied on
      the s1 service and r1 reference.</para>

      <para>Last, you can define several intents on the same
      component/service/reference as following (space-separated):</para>

      <programlisting>&lt;composite xmlns="http://www.osoa.org/xmlns/sca/1.0" &gt;
  
  &lt;component name="myComponent" <emphasis role="bold">requires="foo bar"</emphasis>&gt;
    ...
  &lt;/component&gt;

&lt;/composite&gt;</programlisting>

      <para></para>
Nicolas Dolet's avatar
Nicolas Dolet committed
151
152
153
    </section>
  </section>
</chapter>