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 }