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 }