Kaazing WebSocket Gateway

Orange guy with box of questions

How to Access the HTML5 Communication Protocols from a Java Client

Technology used: Java

This document contains the following sections:

Overview of Java and Java Applets

Java is a programming language developed by Sun Microsystems. Java applications are platform independent, because they are compiled to bytecode, which can then run on a Java virtual machine (JVM) on any certified operating system. A Java applet is a Java program that can be included in an HTML page. Java applets run in the browser's JVM.

For more information about Java and Java applets, visit http://java.com.

WebSocket and Java

Kaazing Gateway provides support for of its HTML 5 Communication protocol libraries in Java. Using the Java client library, you can enable the HTML 5 Communication protocols (for example, server-sent events and WebSocket) in new or existing Java applets. For example, you can create a Java applet that uses WebSocket or ByteSocket to get streaming financial data from a Stomp server, or you can create a Java applet that receives streaming news data through server-sent events.

Note: At this time, only Java applets work with the Java client library (Stand-alone or plugin Java applications do not).

Taking a Look at the Java Client Demo

Before you start, take a look at a demonstration that was built with the Java client library: the Java applet that is part of the Kaazing Gateway demo bundle. To see this Java applet in action, perform the following steps:

  1. Start the Kaazing WebSocket Gateway demo bundle as described in Getting Started.
  2. In a browser, navigate to http://localhost:8000/demo/demo.html#stomp-java.

The demo Java applet uses the Java version of the Simple Text Oriented Message Protocol (Stomp) protocol library.

Setting Up Your Development Environment

To use the Kaazing Java client library in your Java applet, you must include the Kaazing library located in the jar file kaazing-enterprise-gateway-client-release-version.jar. This JAR file can be found in the Kaazing Gateway demo bundle in the directory KAAZING_HOME/lib/client/java. Refer to the Java applet documentation for more information on how to package external code in your Java applet. To deploy your Java applet, you can host it on the Kaazing Gateway. For example, you can place it in the web directory KAAZING_HOME/web.

Using the HTML 5 Communications Protocols in a Java Applet

Note: In this how-to it is assumed that you are familiar with Java applet programming.

This section contains the following subsections:

Using the EventSource API

This section describes how you can use the EventSource API--provided by the Kaazing Java client library--from a Java applet. This API allows you to take advantage of the server-sent events standard as described in the HTML 5 specification. For example, you can create a Java applet that uses the Java HTML 5 Communications client library to receive streaming data from a news feed or streaming financial data. The support for server-sent events is provided by the EventSource class and its supporting classes. The following steps allow you to use the EventSource API in a Java applet. This example highlights some of the most commonly used EventSource methods and is not meant to be an end-to-end tutorial. Refer to the EventSource API documentation for a complete description of all the available methods.

  1. First, add the required import statements:

import com.kaazing.gateway.client.html5.EventSource;
import com.kaazing.gateway.client.html5.EventSourceEvent;
import com.kaazing.gateway.client.html5.EventSourceListener;
import com.kaazing.gateway.client.html5.util.Html5Util;

  1. Next, in order to use the HTML 5 protocol client library, the Java applet must first be registered with the Kaazing Gateway as shown in the following example.

Html5Util.setApplet(this);

  1. Next, create a new EventSource object as shown in the following example.

EventSource mySource = new EventSource();

  1. Next, add a listener to the EventSource object to listen for EventSource events as shown in the following example. The EventSourceListener has three methods: the onOpen method is called when a server-sent events connection is established, the onMessage method is called when messages are received, and the onError method is called when errors occur.

EventSourceListener listener = new EventSourceListener(){

  public void onOpen(EventSourceEvent event) {
    // Update the UI to show that the Java applet is
    // now receiving events.
  }

  public void onMessage(EventSourceEvent event) {
    String data = message.getData();
    String origin = message.getOrigin();
    String lastEvent = message.getLastEventId();

    //
    // Use the data and other information to update the UI.
    //
  }

  public void onError(EventSourceEvent event) {
    // handle errors by closing the application
    // or attempting to reconnect.
  }

}

mySource.addEventSourceListener(listener);

  1. Next, connect to an event source as shown in the following example. Once this method is called, the EventSource is activated and message can flow through at any time.

mySource.connect("http://localhost:8000/sse");

  1. Later, you can call the disconnect method in case you want to stop listening to messages from a particular event source.

mySource.disconnect();

Using the WebSocket API

This section describes how you can use the WebSocket API--provided by the Kaazing Java client library--from a Java applet. This API allows you to take advantage of the WebSocket standard as described in the HTML 5 specification. For example, you can create a Java applet that uses the Java HTML 5 Communications client library to interact directly with a backend chat or Stomp server. The support for WebSocket is provided by the WebSocket class and its supporting classes. The following steps allow you to use the WebSocket API in a Java applet. This example highlights some of the most commonly used WebSocket methods and is not meant to be an end-to-end tutorial. Refer to the WebSocket API documentation for a complete description of all the available methods.

  1. First, add required import statements:

import com.kaazing.gateway.client.html5.WebSocket;
import com.kaazing.gateway.client.html5.WebSocketListener;
import com.kaazing.gateway.client.html5.util.Html5Util;

  1. Next, in order to use the HTML 5 protocol client libraries, the Java applet must first be registered with the Kaazing Gateway as shown in the following example.

Html5Util.setApplet(this);

  1. Next, create a new WebSocket object as shown in the following example.

WebSocket mySocket = new WebSocket();

  1. Next, add a listener to the WebSocket object to listen for WebSocket events as shown in the following example. The WebSocketListener has three methods: the onOpen method is called when a WebSocket connection is established, the onMessage method is called when messages are received, and the onClose method is called when the WebSocket connection is closed.

WebSocketListener listener = new WebSocketListener(){

  public void onOpen(WebSocketEvent event) {
    // Update the UI to show that the Java applet is now connected.
    // Now that the socket is open, you can use mySocket.postMessage
    // to send messages.
  }

  public void onMessage(WebSocketEvent event) {
    String data = message.getData();

    //
    // Use the data and event info to update the UI.
    //
  }

  public void onClose(WebSocketEvent event) {
    // Either reconnect or shut down the application and clean up.
  }

}

mySocket.addWebSocketListener(listener);

  1. Next, use the connect method to connect to a backend service as shown in the following example.

mySocket.connect(new URI("ws://localhost:8001/echo"));

A WebSocket can only connect to one URI at a time.

  1. While the socket is open (that is, after the onOpen listener is called and before the onClose listener is called), you can use the postMessage method to send text-only messages as shown in the following example.

mySocket.postMessage("Hello World");

  1. Later, you can use the disconnect method at any time to deliberately disconnect from the WebSocket server as shown in the following example.

mySocket.disconnect();

Using the ByteSocket API

This section describes how you can use the ByteSocket API--provided by the Kaazing Java client library--from a Java applet. You use the ByteSocket API in the same way you use the WebSocket API, but ByteSocket allows you to establish a bi-directional socket connection that you can use to send and receive binary data. Refer to the ByteSocket API documentation for a complete description of all the available methods.

  1. To use the ByteSocket API, import the ByteBuffer and ByteSocket libraries. To send binary data you must use the Kaazing ByteBuffer class. Unlike the standard Java NIO ByteBuffer class, Kaazing's ByteBuffer class does not use a fixed size. Refer to the ByteBuffer API documentation for more information about ByteBuffer.

import com.kaazing.gateway.client.html5.ByteBuffer;
import com.kaazing.gateway.client.html5.ByteSocket;
import com.kaazing.gateway.client.html5.ByteSocketListener;
import com.kaazing.gateway.client.html5.util.Html5Util;

  1. Next, in order to use the HTML 5 protocol client libraries, the Java applet must first be registered with the Kaazing Gateway as shown in the following example.

Html5Util.setApplet(this);

  1. Next, create a new ByteSocket object as shown in the following example.

ByteSocket mySocket = new ByteSocket();

  1. Next, add a listener to the ByteSocket object to listen for ByteSocket events. The ByteSocketListener has three methods: the onOpen method is called when a ByteSocket connection is established, the onMessage method is called when messages are received, and the onClose method is called when the ByteSocket connection is closed. The onMessage method of the ByteSocket listener must handle binary data as opposed to text data. You can use a ByteBuffer object as shown in bold in the following example.

ByteSocketListener listener = new ByteSocketListener(){

  public void onOpen(ByteSocketEvent event) {
    // Update the UI to show that the Java applet is now connected.
    // Now that the socket is open, you can use mySocket.postMessage
    // to send messages.
  }
 
  public void onMessage(ByteSocketEvent event) {
    ByteBuffer data = event.getData();

    //
    // Use the data and event info to update the UI.
    //
  }

  public void onClose(ByteSocketEvent event) {
    // Either reconnect or shut down the application and clean up.
  }

}

mySocket.addByteSocketListener(listener);

  1. Next, use the connect method to connect to a backend service as shown in the following example.

mySocket.connect(new URI("ws://localhost:8001/echo"));

A ByteSocket can only connect to one URI at a time.

  1. While the socket is open (that is, after the onOpen listener is called and before the onClose listener is called), you can use the postMessage method to send messages. When you send messages, you send binary data using a ByteBuffer object as shown in the following example. Since you are sending binary data, you first have to create a ByteBuffer object in which you store the bytes that you want to send.

// Send a buffer of data.
ByteBuffer toSend = new ByteBuffer();

// ...
// Modify the ByteBuffer and fill it with binary data.
// ...

mySocket.postMessage(toSend);

  1. Later, you can use the disconnect method at any time to deliberately disconnect from the ByteSocket server as shown in the following example.

mySocket.disconnect();

Adding the Applet Tag

To ensure the Java applet works properly, you must add an applet tag with the right applet attributes to the HTML file that includes your Java applet. The following is an example applet tag:

<applet width="800px"
  height="900px"
  type="application/x-java-applet;version=1.6.0_12"
  id="testApplet1"         
  archive="http://localhost:8000/MyApplet.jar"   code="com.mycompany.application.MyApplet"
  mayscript="true"
/>

The following attributes are required if you want to use Kaazing Java client library in your Java applet.

  • type--The version of Java required by this applet. Java version 1.6 update 12 or better is required for the use of the Kaazing Java client library.
  • id--An id that is required for communication between the Java applet and the HTML page.
  • archive--The location (URL) of your Java archive that contains the Java applet code and the Java client library code.
  • code--The name of the Java applet class.
  • mayscript--Specifies whether or not the Java code is allowed to access JavaScript in the HTML page. This attribute must be set to true if you want to use the Kaazing Java client library.

Summary

As you have seen in this how-to, you can access the HTML 5 Communication protocols from a Java applet. Refer to the API documentation for a complete description of all the available methods.