<document>
<localtoc/>

Using a Burlap service from a Java client is like calling a method. The BurlapProxyFactory creates proxies which act like normal Java objects, with possibility that the method might throw a protocol exception if the remote connection fails. Using BurlapProxyFactory requires JDK 1.3.

Each service will have a normal Java interface describing the service. The trivial hello, world example just returns a string. Because the Burlap services support Java serialization, any Java type can be used.

package burlap.test; public interface Basic { public String hello(); }

The following is an example of a standalone Burlap client. The client creates a BurlapProxyFactory. The client uses the factory to create client stubs with the given target URL and a Java interface for the API. The returned object is a stub implementing the API.

package burlap.test; import java.net.URL; import com.caucho.burlap.client.BurlapProxyFactory; public class BasicClient { public static void main(String []args) throws Exception { URL url = new URL("http://www.caucho.com/burlap/test/basic"); BurlapProxyFactory factory = new BurlapProxyFactory(); Basic basic = (Basic) factory.create(Basic.class, url); System.out.println("Hello: " + basic.hello()); } }

There are no more complications to using the client. The service can add methods and use any Java type for parameters and results.

While most Burlap services will use Resin-CMP or Resin-EJB, to take advantage of the benefits of EJB, the Burlap library makes it possible to write services by extending BurlapServlet.

Any public method is treated as a service method. So adding new methods is as easy as writing a normal Java class.

Because the service is implemented as a Servlet, it can use all the familiar servlet data in the ServletContext, just like a normal servlet.

package burlap.test; import com.caucho.burlap.server.BurlapServlet; public class BasicService extends BurlapServlet implements Basic { public String hello() { return "Hello, world"; } }

Burlap can be used for even small Java devices. The following classes from com.caucho.burlap.client can be extracted into a J2ME jar:

- MicroBurlapInput
- MicroBurlapOutput
- BurlapRemote
- BurlapServiceException
- BurlapProtocolException

The following example shows the code for using a cell phone as a client. It's a bit more complicated than using the proxy, since the client is responsible for creating the connection and writing the data.

import javax.microedition.io.Connector; import javax.microedition.io.HttpConnection; ... MicroBurlapInput in = new MicroBurlapInput(); String url = "http://www.caucho.com/burlap/test/basic"; HttpConnection c = (HttpConnection) Connector.open(url); c.setRequestMethod(HttpConnection.POST); OutputStream os = c.openOutputStream(); MicroBurlapOutput out = new MicroBurlapOutput(os); out.call("hello", null); os.flush(); is = c.openInputStream(); MicroBurlapInput in = new MicroBurlapInput(is); Object value = in.readReply(null);

The Burlap classes can be used for serialization and deserialization.

Object obj = ...; OutputStream os = new FileOutputStream("test.xml"); BurlapOutput out = new BurlapOutput(os); out.writeObject(obj); os.close(); InputStream is = new FileInputStream("test.xml"); BurlapInput in = new BurlapInput(is); Object obj = in.readObject(null); is.close();
</document>