One of the typical usecase for WebSocket is online collaborative
games. This Tip Of The Day (TOTD)
explains a sample that can be used to build such games easily.

The application is a collaborative whiteboard where different shapes
can be drawn in multiple colors. The shapes drawn on one browser are
automatically drawn on all other peer browsers that are connected to
the same endpoint. The shape, color, and coordinates of the image
are transfered using a JSON structure. A browser may opt-out of
sharing the figures. Alternatively any browser can send a snapshot
of their existing whiteboard to all other browsers. Take a look at
this video to understand how the application work and the underlying
code.

The Java API for WebSocket has evolved since this sample was first created. Here is the source code corresponding to different builds of GlassFish:

And some radio buttons to choose the color and shape. By default,
the shape, color, and coordinates of any figure drawn on the canvas
are put in a JSON structure and sent as a message to the WebSocket
endpoint. The JSON structure looks like:

FigureDecoderEncoder implements both decoder and encoder
functionality but thats purely for convenience. But the recommended
design pattern is to keep them in separate classes. In certain
cases, you may even need only one of them.

The important part is to set the binaryType property
of WebSocket to arraybuffer. This ensures that any
binary transfers using WebSocket are done using ArrayBuffer
as the default type seem to be blob. The actual binary
data transfer is done using the following:

This comprehensive sample shows the following features of JSR 356
API:

Annotation-driven endpoints

Send/receive text and binary payload in WebSocket

Encoders/decoders for custom text payload

In addition, it also shows how images can be captured and drawn
using HTML5 Canvas in a JSP.

How could this be turned in to an online game ? Imagine drawing a
Tic-tac-toe
board on the canvas with two players playing and others watching.
Then you can build access rights and controls within the
application itself. Instead of sending a snapshot of the canvas on
demand, a new peer joining the game could be automatically
transferred the current state as well. Do you want to build this
game ?

I built a similar game a
few years ago. Do somebody want to rewrite the game using
WebSocket APIs ? :-)

Tuesday Nov 27, 2012

Servlet 3.0 allowed asynchronous request processing but only
traditional I/O was permitted. This can restrict scalability of your
applications. In a typical application, ServletInputStream is read
in a while loop.

If the incoming data is blocking or streamed slower than the server
can read then the server thread is waiting for that data. The same
can happen if the data is written to ServletOutputStream.

This is resolved in Servet 3.1 (JSR 340, to be
released as part Java EE 7) by adding event
listeners - ReadListener and WriteListener
interfaces. These are then registered using ServletInputStream.setReadListener
and ServletOutputStream.setWriteListener. The
listeners have callback methods that are invoked when the content is
available to be read or can be written without blocking.

Invoking setXXXListener methods indicate that
non-blocking I/O is used instead of the traditional I/O. At most one
ReadListener can be registered on ServletIntputStream
and similarly at most one WriteListener can be
registered on ServletOutputStream. ServletInputStream.isReady
and ServletInputStream.isFinished are new methods to
check the status of non-blocking I/O read. ServletOutputStream.canWrite
is a new method to check if data can be written without blocking.

onDataAvailable callback method is called
whenever data can be read without blocking

onAllDataRead callback method is invoked data for
the current request is completely read.

onError callback is invoked if there is an error
processing the request.

Notice, context.complete() is called in onAllDataRead
and onError to signal the completion of data read.

For now, the first chunk of available data need to be read in the doGet
or service method of the Servlet. Rest of the data can
be read in a non-blocking way using ReadListener after
that. This is going to get cleaned up where all data read can happen
in ReadListener only.

Monday Nov 26, 2012

EJB 3.1 added a whole ton of features for simplicity and ease-of-use
such as @Singleton, @Asynchronous, @Schedule, Portable JNDI name,
EJBContainer.createEJBContainer, EJB 3.1 Lite, and many others. As
part of Java EE 7, EJB 3.2 (JSR 345) is making
progress and this blog will provide highlights from the work done so
far. This release has been particularly kept small but include
several minor improvements and tweaks for usability.

More features in EJB.Lite

Asynchronous session bean

Non-persistent EJB Timer service

This also means these features can be used in embeddable EJB
container and there by improving testability of your
application.

Pruning - The following features were made Proposed Optional
in Java EE 6 and are now made optional.

EJB 2.1 and earlier Entity Bean Component Contract for CMP
and BMP

Client View of an EJB 2.1 and earlier Entity Bean

EJB QL: Query Language for CMP Query Methods

JAX-RPC-based Web Service Endpoints and Client View

The optional features are moved to a separate document and as
a result EJB specification is now split into Core and Optional
documents. This allows the specification to be more readable
and better organized.

The specification is still evolving so the actual property or
method names or their actual behavior may be different from the
currently proposed ones.

Are there any improvements that you'd like to see in EJB 3.2 ?
The EJB 3.2 Expert Group would love to hear
your feedback. An Early
Draft of the specification is available. The latest version
of the specification can always be downloaded from here.

Wednesday Nov 21, 2012

JPA 2.1 specification is now final and can be download from
here. The Reference Implementation is integrated in GlassFish
4 Promoted Builds (soon to be final). The Schema Generation
property names have changed since the blog was originally published
and is now updated in the table below.

Blog from Nov 11, 2012

This blog explained
some of the key
features
of JPA 2.1 earlier. Since then Schema Generation has been
added to JPA 2.1. This Tip Of The Day
(TOTD)
will provide more details about this new feature in JPA 2.1.

Schema Generation refers to generation of database artifacts like
tables, indexes, and constraints in a database schema. It may or may
not involve generation of a proper database schema depending upon
the credentials and authorization of the user. This helps in
prototyping of your application where the required artifacts are
generated either prior to application deployment or as part of
EntityManagerFactory creation. This is also useful in environments
that require provisioning database on demand, e.g. in a cloud.

This feature will allow your JPA domain object model to be directly
generated in a database. The generated schema may need to be tuned
for actual production environment. This usecase is supported by
allowing the schema generation to occur into DDL scripts which can
then be further tuned by a DBA.

The following set of properties in persistence.xml or specified
during EntityManagerFactory creation controls the behaviour of
schema generation.

Property Name

Purpose

Values

javax.persistence.schema-generation.database.action

Specifies the action to be taken by the
persistence provider with regard to the database artifacts
Per.book

"none", "create", "drop-and-create", "drop"

javax.persistence.schema-generation.scripts.action

Specifies which scripts are to be generated
by the persistence provider
Per.book

Specifies locations from which DDL scripts
are to be read. Readers are pre-configured for the
persistence provider.

java.io.Reader (e.g. MyReader.class) or URL
strings

javax.persistence.schema-generation.connection

JDBC connection to be used for schema
generation

javax.persistence.sql-load-script-source

Specifies location of SQL bulk load script.

java.io.Reader (e.g. MyReader.class) or URL
string

Section 11.2 in the JPA
2.1
specification defines the annotations used for schema
generation process. For example, @Table, @Column, @CollectionTable,
@JoinTable, @JoinColumn, are used to define the generated schema.
Several layers of defaulting may be involved. For example, the table
name is defaulted from entity name and entity name (which can be
specified explicitly as well) is defaulted from the class name.
However annotations may be used to override or customize the values.

"name" is mapped to NAME column with a default VARCHAR(255).
The length of this field can be easily tuned using @Column.

@ManyToOne is mapped to DEPT_ID foreign key column. Can be
customized using JOIN_COLUMN.

In addition to these properties, couple of new annotations are
added to JPA 2.1:

@Index - An index for the primary key is generated by default
in a database. This new annotation will allow to define
additional indexes, over a single or multiple columns, for a
better performance. This is specified as part of @Table,
@SecondaryTable, @CollectionTable, @JoinTable, and
@TableGenerator. For example:

The generated table will have a default index on the primary
key. In addition, two new indexes are defined on the NAME column
(default ascending) and the foreign key that maps to the
department in descending order.

@ForeignKey - It is used to define foreign key constraint or
to otherwise override or disable the persistence provider's
default foreign key definition. Can be specified as part of
JoinColumn(s), MapKeyJoinColumn(s), PrimaryKeyJoinColumn(s). For
example:

JPA 2.1 will be delivered as part of Java EE 7. The different
components in the Java EE 7 platform are tracked
here.

JPA 2.1 Expert Group has released Early
Draft
2 of the specification. Section 9.4 and 11.2 provide all
details about Schema Generation. The latest javadocs can be
obtained from
here. And the JPA EG would appreciate
feedback.

Thursday Nov 15, 2012

TOTD #185 explained how to process text and binary payloads in
a WebSocket endpoint. In summary, a text payload may be received as

public void receiveTextMessage(String message) { . . . }

And binary payload may be received as:

public void recieveBinaryMessage(ByteBuffer message) { . . .}

As you realize, both of these methods receive the text and binary
data in raw format. However you may like to receive and send the
data using a POJO. This marshaling and unmarshaling can be done in
the method implementation but JSR 356 API provides a cleaner way.
For encoding and decoding text payload into POJO, Decoder.Text
(for inbound payload) and Encoder.Text (for outbound
payload) interfaces need to be implemented.

A sample implementation below shows how text payload consisting of
JSON structures can be encoded and decoded.

In this implementation, the decode method decodes
incoming text payload to MyMessage, the encode
method encodes MyMessage for the outgoing text
payload, and the willDecode method returns true
or false if the message can be decoded.

The encoder and decoder implementation classes need to be specified
in the WebSocket endpoint as:

Notice the updated method signature where the application is working
with MyMessage instead of the raw string.

Note that the encoder and decoder implementations just illustrate
the point and provide no validation or exception handling. Similarly
Encooder.Binary and Decoder.Binary
interfaces need to be implemented for encoding and decoding binary
payload.

The return type is void and that means no response is
returned to the client that invoked this endpoint. A response may be
returned to the client in two different ways. First, set the return
type to the expected type, such as:

This shows how duplex and asynchronous communication between the two
endpoints can be achieved. This can be used to define different
message exchange patterns between the client and server.

The WebSocket client can send the message as:

websocket.send(myTextField.value);

where myTextField is a text field in the web page.

Binary payload in the incoming WebSocket frame can be received if ByteBuffer
is used as the first parameter of the method signature. The endpoint
method signature in that case would look like:

public void receiveBinaryMessage(ByteBuffer message) {
. . .
}

From the client side, the binary data can be sent using Blob,
ArrayBuffer, and ArrayBufferView. Blob is
a just raw data and the actual interpretation is left to the
application. ArrayBuffer and ArrayBufferView
are defined in the TypedArray
specification and are designed to send binary data using
WebSocket. In short, ArrayBuffer is a fixed-length
binary buffer with no format and no mechanism for accessing its
contents. These buffers are manipulated using one of the views
defined by one of the subclasses of ArrayBufferView
listed below:

Int8Array (signed 8-bit integer or char)

Uint8Array (unsigned 8-bit integer or unsigned
char)

Int16Array (signed 16-bit integer or short)

Uint16Array (unsigned 16-bit integer or unsigned
short)

Int32Array (signed 32-bit integer or int)

Uint32Array (unsigned 16-bit integer or unsigned
int)

Float32Array (signed 32-bit float or float)

Float64Array (signed 64-bit float or double)

WebSocket can send binary data using ArrayBuffer with
a view defined by a subclass of ArrayBufferView or a
subclass of ArrayBufferView itself.

Wednesday Nov 07, 2012

TOTD
#183 explained how to build a WebSocket-driven application
using GlassFish 4. This Tip Of The Day
(TOTD) will explain how do view/debug on-the-wire messages, or
frames as they are called in WebSocket parlance, over this upgraded
connection. This blog will use the application built in TOTD
#183.

First of all, make sure you are using a browser that supports
WebSocket. If you recall from TOTD
#183 then WebSocket is combination of Protocol and JavaScript API. A
browser supporting WebSocket, or not, means they understand your web
pages with the WebSocket JavaScript. caniuse.com/websockets
provide a current status of WebSocket support in different browsers.
Most of the major browsers such as Chrome, Firefox, Safari already
support WebSocket for the past few versions. As of this writing, IE
still does not support WebSocket however its planned for a future
release.

Viewing WebSocket farmes require special settings because all the
communication happens over an upgraded HTTP connection over a single
TCP connection. If you are building your application using Java,
then there are two common ways to debug WebSocket messages today.
Other language libraries provide different mechanisms to log the
messages.

Lets get started!

Chrome
Developer Tools provide information about the initial
handshake only. This can be viewed in the Network tab and selecting
the endpoint hosting the WebSocket endpoint.

You can also click on "WebSockets" on the bottom-right to show only
the WebSocket endpoints.

Click on "Frames" in the right panel to view the actual frames being
exchanged between the client and server.

The frames are not refreshed when new messages are sent or received.
You need to refresh the panel by clicking on the endpoint again.

To see more detailed information about the WebSocket frames, you
need to type "chrome://net-internals"
in a new tab. Click on "Sockets" in the left navigation bar and then
on "View live sockets" to see the page.

Select the box with the address to your WebSocket endpoint and see
some basic information about connection and bytes exchanged between
the client and the endpoint.

Clicking on the blue text "source dependency ..." shows more details
about the handshake.

If you are interested in viewing the exact payload of WebSocket
messages then you need a network sniffer. These tools are used to
snoop network traffic and provide a lot more details about the raw
messages exchanged over the network. However because they provide
lot more information so they need to be configured in order to view
the relevant information.

Wireshark (nee Ethereal) is a
pretty standard tool for sniffing network traffic and will be used
here. For this blog purpose, we'll assume that the WebSocket
endpoint is hosted on the local machine. These tools do allow to
sniff traffic across the network though. Wireshark is quite a
comprehensive tool and we'll capture
traffic on the loopback address.

Start wireshark, select "loopback" and click on "Start".

By default, all traffic information on the loopback address is
displayed. That includes tons of TCP protocol messages, applications
running on your local machines (like GlassFish or Dropbox on mine),
and many others. Specify "http" as the filter in the top-left.
Invoke the application built in TOTD
#183 and click on "Say Hello" button once. The output in
wireshark looks like

Sunday Nov 04, 2012

JMaghreb is the
inaugural Java conference organized by Morocco JUG. It is the biggest
Java conference in Maghreb
(5 countries in North West Africa).

Oracle was the exclusive platinum sponsor with several others. The
registrations had to be closed at 1412 for the free conference and
several folks were already on the waiting list. Rabat with 531
registrations and Casablanca with 426 were the top cities. Some
statistics ...

Java EE 6 hands-on lab was sold out within 7 minutes and
JavaFX in 12 minutes

I gave the keynote along with Simon Ritter which was basically a
recap of the Strategy
and Technical
keynotes presented at JavaOne 2012.
An informal survey during the keynote showed the following numbers:

25% using NetBeans, 90% on Eclipse, 3 on JDeveloper, 1 on
IntelliJ

About 10 subscribers to free online Java
magazine. This digital magazine is a comprehensive source
of information for everything Java - subscribe
for free!!

My second talk explained the core concepts of WebSocket and how JSR 356 is
providing a standard API to build WebSocket-driven applications in
Java EE 7. TOTD
#183 explains how you can easily get started with WebSocket in
GlassFish
4. The complete slide deck is available:

Next day started with a community keynote by Sonya Barry. Some of us
live the life of JCP, JSR, EG, EC, RI, etc every day, but not every
body is. To address that, Sonya prepared an excellent introductory
presentation providing an explanation of these terms and how
java.net infrastructure supports Java development.

The registration for the lab showed there is a definite demand for
these technologies in this part of the world. I delivered the Java
EE 6 hands-on lab to a packed room of about 120 attendees. Most of
the attendees were able to progress and follow the lab instructions.
Some of the attendees did not have a laptop but were taking
extensive notes on paper notepads. Several attendees were already
using Java EE 6 in their projects and typically they are the ones
asking deep dive questions. Also gave out three copies of my
recently released Java
EE 6 Pocket Guide and new GlassFish
t-shirts. Definitely feels happy to coach ~120 more Java
developers learn standards-based enterprise Java programming.

I also participated in a JCP BoF along with Werner, Sonya, and Badr.
Adotp-a-JSR, java.net infrastructure, how to file a JSR, what is an
RI, and other similar topics were discussed in a candid manner.

You can follow @JMaghrebConf
or check out their facebook
page. java.net published a timely conversation
with Badr El Houari - the fearless leader of the Morocco JUG
team. Did you know that Morocco JUG stood for JCP EC elections (ADD
LINK) ? Even though they did not get elected but did fairly well.

#JMaghreb is over. Impressive for a first edition! Thanks
@badrelhouari and all the @MoroccoJUG team ! Since you @speakjava : System.out.println("Thank you so much
dear Tech Evangelist ! The JavaFX was pretty amazing !!! ");
#JMaghreb @YounesVendetta @arungupta @JMaghrebConf Right ! hope he
will be back to morocco again and again .. :) @Alji_ @arungupta @JMaghrebConf That dude is a genius ;) Put
it on your wall :p @arungupta rocking Java EE 6 at @JMaghrebConf #Java #JavaEE
#JMaghreb http://t.co/isl0Iq5p @sonyabarry you are an awesome speaker ;-) #JMaghreb rich more than 550 attendees in day one. Expecting
more tomorrow! ongratulations @badrelhouari the organisation was great! The
talks were pretty interesting, and the turnout was surprising at
#JMaghreb! #JMaghreb is truly awesome... The speakers are unbelievable
! #JavaFX... Just amazing #JMaghreb Charmed by the talk about #javaFX ( nodes architecture, MVC,
Lazy loading, binding... ) gotta start using it intead of SWT.
#JMaghreb JavaFX is killing JFreeChart. It supports Charts a lot of
kind of them ... #JMaghreb The british man is back #JMaghreb I do like him!! #JMaghreb @arungupta rocking @JMaghrebConf.
pic.twitter.com/CNohA3PE @arungupta Great talk about the future of Java EE (JEE 7
& JEE 8) Thank you. #JMaghreb JEE7 more mooore power , leeess less code !! #JMaghreb They are simplifying the existing API for Java Message
Service 2.0 #JMaghreb good to know , the more the code is
simplified the better ! The Glassdoor guy #arungupta is doing it RIGHT ! #JMaghreb Great presentation of The Future of the Java Platform: Java
EE 7, Java SE 8 & Beyond #jMaghreb @arungupta is a great Guy apparently #JMaghreb
On a personal front, the hotel (Soiftel Jardin des Roses) was pretty
nice and the location was perfect. There was a 1.8 mile loop dirt
trail right next to it so I managed to squeeze some runs before my upcoming marathon. Also enjoyed
some great Moroccan cuisine - Couscous, Tajine, mint tea,
and moroccan salad. Visit to Kasbah of
the Udayas, Hassan II
(one of the tallest
mosque in the world), and eating in a restaurant in a kasbah
are some of the exciting local experiences.

Now some pictures from the event (and around the city) ...

And the complete album:

Many thanks to Badr, Faisal, and rest of the team for organizing a
great conference. They are already thinking about how to improve the
content, logisitics, and flow for the next year. I'm certainly
looking forward to JMaghreb 2.0 :-)

As evident, all the components have released at least an Early Draft
specification. Some have released second Early Draft and some even
have a Public Review in different stages. Several implementations
are already integrated in GlassFish
4. Promoted Builds.