Action Plug-ins

 Action Plug-ins
Action plug-ins consists of a new modern and rapid way to implement jWebSocket Token plug-ins. Technically is an extension for the TokenPlugIn class that provides automatically support for:
  • Capturing and notifying intentionally uncaught exceptions.
  • Supporting actions annotations.
 
An action is any public method that is postfixed with the “Action” word and is defined using the following signature:
 
public void loginAction(WebSocketConnector aConnector, Token aToken) throws Exception;
 
 
Dependencies
 
Action plug-ins has not extra dependencies.
 
Configuration
 
Action plug-ins has not extra configuration.
 
Creating Action plug-ins
 
Creating an action plug-ins is basically extends the “org.jwebsocket.plugins.ActionPlugIn” class:
 
public class MyTestPlugIn extends ActionPlugIn {

	public MyTestPlugIn(PluginConfiguration aConfiguration) {
		super(aConfiguration);
		setNamespace(aConfiguration.getNamespace());
	}

	@Authenticated
	public void sayHelloAction(WebSocketConnector aConnector, Token aReq) {
		Token lResponse = createResponse(aReq);
		lResponse.setString("msg", "Hello " + aConnector.getUsername()
				+ ", you are already authenticated!");

		sendToken(aConnector, lResponse);
	}
}
 
 
The client plug-in library:
 
jws.MyTestPlugIn = {
		sayHello: function(aOptions) {
		this.sendToken({
		ns: "my.company.testplugin",
		type: "sayHello"
		}, aOptions);
	}
};
jws.oop.addPlugIn(jws.jWebSocketTokenClient, jws.MyTestPlugIn );
 
Setting up the new plug-in for the server startup (jWebSocket.xml):
<plugin>
 <name>my.company.TestPlugIn</name>
 <id>testplugin</id>
 <ns>my.company.testplugin</ns>
 <jar>TestPlugIn-1.0.jar</jar>
 <settings>
 </settings>
 <server-assignments>
    <server-assignment>ts0</server-assignment>
 </server-assignments>
</plugin>
 
 
Invoking the action from the client:
…
<script src="libs/TestPlugIn.js" type="text/javascript"></script>
…
 
lClient.sayHello({
 OnSuccess: function(aResponse){
               alert(aResponse.msg);        
 }
});
 
 
jWebSocket built-in annotations:
 
The jWebSocket server comes with a few useful annotations that you can commonly use in your action plug-ins:
  • @Authenticated: Using this annotation restrict your action to be executed by authenticated users only.
  • @Role(name = ”required role name”): Using this annotation restrict your action to be executed only by users that has the given role (authority).
  • @Roles(names = {“ADMIN”, “USER”}, requireAll = false): Using this annotation restrict your action to be executed only by users that has the given roles list (if requireAll is false, only one role is required).
  • @RequirePlugIn(id = “required plugin id”): Using this annotation guarantee that your action is executed only if the given plug-in is properly running. Useful to remove internal checks for inter plug-ins dependencies.
  • @RequirePlugIns(ids = {“plugin A”, “plugin B”}): Same effect than @RequirePlugIn but passing a plug-ins identifiers list.
  • @RequireConnection(name = “a connection name”): Using this annotation guarantee that your action is executed only if the given connection is valid. The annotation processor queries the ConnectionManager component declared in “conf/Resources/bootstrap.xml”. The default connection manager implementation supports MongoDB, JMS and JDBC connection types.
 Supporting custom annotations
 
Developers can optionally define and support custom annotations following the steps:
  1. Define your new Annotation type.
  2. Implement the “org.jwebsocket.api.IAnnotationProcessor” interface to support your annotation.
  3. Register the annotation processor in the AnnotationManager component (conf/SystemPlugIn/system.xml):
 
<!-- Annotation Manager for ActionPlugIn annotations support -->
 <!-- Default implementation supports annotations from package
         org.jwebsocket.plugins.annotations -->
 <bean id="annotationManager"  
    class="org.jwebsocket.plugins.annotations.DefaultAnnotationManager">
    <property name=”processors”>
      <list>
        … your processors here …
      </list>
    </property>
 </bean>
 
Intentionally throwing exceptions inside actions
 
Action plug-ins developers can intentionally throw exceptions inside the actions logic in order to notify the calling client that something was wrong. Just imagine that we  want to simply perform some data validation before start the action logic flow (exception is thrown if username does not matches a regular expression):
 
public void sayHelloAction(WebSocketConnector aConnector, Token aReq) {
 String lUsername = aReq.getString("username", "");
 Assert.isTrue(lUsername.matches(USERNAME_REGEX),
      "Invalid username value!");
  …
 
Note:
If an uncaught exception is thrown during the action execution, the calling client is notified with an error response containing the exception localized message in the “msg” property.
 
 
Sending “error” responses to the client

Developers can also get benefits of the method "fail" to easily send back to the action calling client an error message.

 
fail("Unable to connect with the database server. Try later!");
fail(-5, "Error message with custom error code!");
 
 

Copyright © 2013 Innotrade GmbH. All rights reserved.