ScrudJavaServer

Scrud is a JSON based messaging format designed to be used over web sockets. In addition to normal CRUD operation is supports subscriptions.

The ScrudJavaServer is a framework which facilitates using Scrud to create a J2EE server application.

Scrud Messaging format

Subscriptions

Initiating a subscription

Subscriptions are initiated by the client with a subscribe with the following properties:

Name	Type	Description or Content
message-type	String	subscribe
client-id	String	A string which will be included in all messages relating to the resultant subscription
resource-type	String	The type of resource for the subscription
resource-id	String	Optionally specify an id so only one resource is returned
filter	unknown	The filter which will be evaluated to determine if resources match the subscription

Note that filters are not currently supported.

A reply will be sent for a successful subscription with the following properties:

Name	Type	Description or Content
message-type	String	subscription-success
client-id	String	The client-id provided by the client in the subscribe message
resources	JSON object containing resources mapped by their id	The current resources matching this subscription

An unsuccessful subscription will result in a message with the following properties:

TODO

Messages from the server relating to a subscription

Once a subscription is active the server can send a message indicating a new matching resource has been created:

Name	Type	Description or Content
message-type	String	created
client-id	String	The client-id provided by the client in the subscribe message
resource-id	String	The server side id of the newly created resource
resource	Object	The newly created resource

Or if a resource changes:

Name	Type	Description or Content
message-type	String	updated
client-id	String	The client-id provided by the client in the subscribe message
resource-id	String	The server side id of the modified resource
resource	Object	The modified resource

When a resource is deleted:

Name	Type	Description or Content
message-type	String	updated
client-id	String	The client-id provided by the client in the subscribe message
resource-id	Object	The modified resource

Since a resource may be relevant to multiple subscriptions the server must send a message per matching subscription when a resource is created, updated or deleted.

When a resource no longer matches the filter for a subscription the following is sent:

Name	Type	Description or Content
message-type	String	no-longer-matches
client-id	String	The client-id provided by the client in the subscribe message
resource-id	String	The server side id of the modified resource
resource	Object	The modified resource

Messages from the client relating to a subscription

When a subscription is active a client may choose to end that subscription:

Name	Type	Description or Content
message-type	String	unsubscribe
client-id	String	The client-id provided by the client in the subscribe message

No response is sent from the server, whilst it is being processed additional messages relating to the subscription could be received but can be ignored.

Create

To create a resource the client sends a message with the following properties:

Name	Type	Description or Content
message-type	String	create
client-id	String	A string which will be included in the server's response
resource-type	String	The type of resource for the creation
resource	Object	The resource to create

The response for a successful creation will have the following properties:

Name	Type	Description or Content
message-type	String	create-success
client-id	String	The client-id provided by the client in the create message
resource-id	String	The server side id of the newly created resource
resource	Object	The newly created resource

The response if the create failed will contain the following:

TODO

Read

TODO Not convinced a one time read is necessary as you can read a single resource with subscribe

Update

To update an existing resource the client sends through a message with the following properties

Name	Type	Description or Content
message-type	String	update
client-id	String	A string which will be included in the server's response
resource-id	String	The server side id of the resource to update
resource-type	String	The type of resource to update
resource	Object	The new state of the resource

The response for a successful update will have the following properties:

Name	Type	Description or Content
message-type	String	update-success
client-id	String	The client-id provided by the client in the update message
resource-id	String	The server side id of the updated resource
resource	Object	The updated resource

The response if update failed will contain the following:

TODO

Delete

TODO

Restrictions

• If a client has a subscription to a resource type and then creates a resource of that type the server will need to send two messages to the client, created and create-success. The created message must be sent by the server first, this allows the client to avoid creating duplicate objects to represent a resource.