View Javadoc

1   package org.controlhaus.xfire.client;
2   
3   import org.apache.xmlbeans.XmlObject;
4   import org.codehaus.xfire.fault.XFireFault;
5   
6   import org.apache.beehive.controls.api.bean.ControlInterface;
7   import org.apache.beehive.controls.api.properties.PropertySet;
8   import org.apache.beehive.controls.api.events.EventSet;
9   
10  import java.io.IOException;
11  import java.lang.annotation.Retention;
12  import java.lang.annotation.RetentionPolicy;
13  import java.lang.annotation.Target;
14  import java.lang.annotation.ElementType;
15  
16  /***
17   * An XFire client control.  Included are two annotations which
18   * can be used to configure the control.  Encoding, which will specify
19   * the encoding. It defaults to UTF-8.  Also the ServiceUrl annotation
20   * will specify which url to invoke for the service.
21   * <p>
22   * A typical usage would look like so:
23   * <pre>
24   *  {@literal @}Encoding("UTF-8")
25   *  {@literal @}ServiceUrl("http://some.service.com")
26   *  {@literal @}Control XFireClientControl client;
27   * </pre>
28   * <p>
29   * It is possible to set the service url on a per invocation basis
30   * if you declare the control "Bean" instead of just XFireClientControl. For
31   * example in your class you would declare,
32   * <pre>
33   * {@literal @}Control XFireClientControlBean xfire;
34   * </pre>
35   * <p>
36   * You could then set the URL like so:
37   * <pre>
38   * xfire.setServiceUrl("http://your/url");
39   * </pre>
40   * @author <a href="mailto:dan@envoisolutions.com">Dan Diephouse</a>
41   * @since Nov 5, 2004
42   */
43  @ControlInterface
44  public interface XFireClientControl
45  {
46  
47      /***
48       * Invoke a SOAP service.
49       * 
50       * @param request The request as XMLBeans.
51       * @return The response as XMLBeans.
52       * @throws XFireFault
53       */    
54      XmlObject[] invoke( XmlObject[] request ) 
55  		throws IOException, XFireFault;
56  
57      /***
58       * Invoke a SOAP service.
59       * 
60       * @param request The request as XMLBeans.
61       * @param requestHeaders The SOAP Headers, if there are any. Otherwise <code>null</code>.
62       * @return The response as XMLBeans.
63       * @throws XFireFault
64       */
65      XmlObject[] invoke( XmlObject[] request, XmlObject[] reqHeaders ) 
66      	throws IOException, XFireFault;
67      
68      /***
69       * Invoke a SOAP service. Listen for the response using the Control's
70       * Event mechanism.
71       * 
72       * @param request The request as XMLBeans.
73       * @param requestHeaders The SOAP Headers, if there are any. Otherwise <code>null</code>.
74       * @return The response as XMLBeans.
75       * @throws XFireFault
76       */
77      @Asynchronous
78      void beginInvoke( XmlObject[] request, XmlObject[] reqHeaders );
79      
80      @EventSet
81      public interface EndInvokeCallback 
82      {
83          /***
84           * Called at the end of an asynchronous request which has completed successfully
85           * (i.e. there was no fault).
86           * 
87           * @param response
88           * @param responseHeaders
89           */
90          public void endInvoke( XmlObject[] response, XmlObject[] responseHeaders );
91          
92          /***
93           * Called if a fault occurs during the service invocation.
94           * 
95           * @param fault The fault.
96           */
97          public void handleFault( XFireFault fault );
98      }
99      
100     @PropertySet(prefix="Encoding")
101     @Target( {ElementType.TYPE, ElementType.FIELD, ElementType.METHOD} )
102     @Retention(RetentionPolicy.RUNTIME)
103     public @interface Encoding
104     {
105         String value() default "UTF-8";
106     }
107     
108     @PropertySet(prefix="ServiceUrl")
109     @Target( {ElementType.TYPE, ElementType.FIELD, ElementType.METHOD} )
110     @Retention(RetentionPolicy.RUNTIME)
111     public @interface ServiceUrl
112     {
113         String value();
114     }
115     
116     /***
117      * Declares a parameter in an control a Soap Header in a control
118      * which extends the XFireClientControl.
119      */
120     @PropertySet(prefix="SoapHeader")
121     @Target( {ElementType.TYPE, ElementType.PARAMETER, ElementType.METHOD} )
122     @Retention(RetentionPolicy.RUNTIME)
123     public @interface SoapHeader
124     {
125     }
126 
127     /***
128      * Marks a method on a control which extends the XFireClientControl
129      * as ansynchronous.  As a result, a new thread to invoke the service
130      * will be launced and the method will return immediately.
131      */
132     @Target( {ElementType.TYPE, ElementType.FIELD, ElementType.METHOD} )
133     @Retention(RetentionPolicy.RUNTIME)
134     public @interface Asynchronous
135     {
136     }
137 }