Project setup
This short guide shows how to create Bristleback application in several ways. In all examples, we use Maven as our build tool. In addition, Bristleback Framework always use Spring Framework.
Our webapp archetype is on main Maven repository. In addition, we host a special archetypes catalog from which the archetype can be downloaded. To run your first Bristleback application, you must perform only few steps:
1. Go to directory where your new Bristleback Project will be placed and type:
mvn archetype:generate -DarchetypeGroupId=pl.bristleback -DarchetypeArtifactId=webapp-archetype -DarchetypeVersion=0.3.5
2. Enter additional information about the project.
3. Go to the newly created project directory and type:
mvn jetty:run
Your first Bristleback application with Jetty as the Server Engine is starting!
4. Open your browser and type localhost:8080
5. Have fun developing!
Fallowing two subsections describe how to run Bristleback application project from scratch.
Now, we'll develop a standalone application.
Firstly, we need to create new Maven project. It can be done using any modern Java IDE or using Maven archetype:
mvn archetype:generate \
-DgroupId=com.yourpackage.sample \
-DartifactId=chatapp \
-Dversion=1.0-SNAPSHOT \
-DpackageName=com.yourpackage.sample.chatapp \
-DarchetypeGroupId=org.apache.maven.archetypes \
-DarchetypeArtifactId=maven-archetype-quickstart \
-DarchetypeVersion=1.1 \
-DinteractiveMode=false
Created in this way, the project can be then imported into your IDE, for example by using fallowing command: mvn idea:idea (for IntelliJ Idea).
The next step is to modify generated pom.xml file to include Bristleback dependencies.
In <dependencies></dependencies> section add:
<dependency>
<groupId>pl.bristleback</groupid>
<artifactId>bristleback-core</artifactid>
<version>0.3.5</version>
</dependency>
<dependency>
<groupId>pl.bristleback</groupid>
<artifactId>serialization-engine-jackson</artifactid>
<version>0.3.5</version>
</dependency>
Bristleback uses Spring Framework, so it's necessary to add Spring dependencies as well:
<dependency>
<groupId>org.springframework</groupid>
<artifactId>spring-context</artifactid>
<version>${org.springframework.version}</version>
</dependency>
<dependency>
<groupId>org.springframework</groupid>
<artifactId>spring-webmvc</artifactid>
<version>${org.springframework.version}</version>
</dependency>
Replace ${org.springframework.version} placeholder with the version you would like to use, we support versions 3.1.1.RELEASE or higher.
- If you want to use Jetty as the Websocket engine
<dependency>
<groupId>pl.bristleback</groupid>
<artifactId>websocket-engine-jetty</artifactid>
<version>0.3.5</version>
</dependency>
- If you want to use Netty as the Websocket engine
<dependency>
<groupId>pl.bristleback</groupid>
<artifactId>websocket-engine-netty</artifactid>
<version>0.3.5</version>
</dependency>
- If you want to use Apache Tomcat as the Websocket engine
<dependency>
<groupId>pl.bristleback</groupid>
<artifactId>websocket-engine-tomcat</artifactid>
<version>0.3.5</version>
</dependency>
Then we create applicationContext.xml file, in which whole Bristleback configuration will be placed. Go to the src/main directory, create a new directory resources, this is the place where applicationContext.xml file should be placed. The content of this file is presented below.
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:bb="http://www.bristleback.pl/schema/bristleback"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context-2.5.xsd
http://www.bristleback.pl/schema/bristleback
http://www.bristleback.pl/schema/bristleback/bristleback.xsd">
<context:component-scan base-package="com.yourpackage.sample.chatapp"/>
<bb:serverMessages/>
<bean id="pojoConfigResolver" class="pl.bristleback.server.bristle.conf.resolver.init.PojoConfigResolver">
</bean>
<bb:standaloneServer configurationResolver="pojoConfigResolver"/>
</beans>
If you use different server engine than standalone Jetty, first thing you need to change in your configuration is a name of server engine, for example:
<bean id="pojoConfigResolver" class="pl.bristleback.server.bristle.conf.resolver.init.PojoConfigResolver">
<property name="engineName" value="system.engine.tomcat.servlet"/>
</bean>
Above sample configuration will point Bristleback to use Tomcat Servlet engine to serve as the Websocket protocol implementation. You can find more information about server engines configuration in chapter Configuration - deeper look.
Bristleback has its own namespace so we had to import it. In the next line after import section, we enabled automatic Spring beans scanning. <bb:serverMessages/> tag is required to enable server messages and client action messages. Finally, we defined configuration resolver bean and Bristleback Server bean. By default, server starts immediately in bean init phase.
Now we just need to initialize Spring in our main() method. To do so, we modify generated App class:
public final class App {
private static final String[] CONFIG_FILES =
{"applicationContext.xml"};
private App() {
}
public static void main(String[] args) {
ApplicationContext applicationContext = new ClassPathXmlApplicationContext(CONFIG_FILES);
StandaloneServerRunner runner = (StandaloneServerRunner) applicationContext.getBean("bristlebackStandaloneServer");
Scanner in = new Scanner(System.in);
String value = in.nextLine();
while (!value.equalsIgnoreCase("x")) {
value = in.nextLine();
}
runner.stopServer();
}
}
Now you may run App class, server should start. The only thing remaining is to build some webpage to test the connection. This page will contain two buttons for connecting/disconnecting and a status container. Required client library can be found here.
<html>
<head>
<script type="text/javascript" src="./bristleback-0.3.5.js"></script>
<script type="text/javascript">
var config = {
serverUrl: "ws://localhost:8765/websocket",
onOpen: function(event) {
document.getElementById('status').innerHTML = "The WebSocket Connection Is Open.";
},
onClose: function(event) {
document.getElementById('status').innerHTML = "The WebSocket Connection Is Closed.";
}
};
var client = Bristleback.newClient(config);
var dataController = client.dataController;
function connect() {
client.connect();
}
function closeConnection() {
client.disconnect();
}
</script>
</head>
<body>
<div id="status">Click connect button to start playing.</div>
<div>
<input type="button" onclick="connect()" value="Connect">
<input type="button" onclick="closeConnection()" value="Close connection">
</div>
</body>
</html>
Few parts of this subsection are copied from the previous subsection.
Creating web application with Bristleback Framework enabled is almost as easy as creating standalone application. Again we start by creating the new Maven project, IDE or Maven archetype can be used.
mvn archetype:generate \
-DgroupId=com.yourpackage.sample \
-DartifactId=chatapp \
-Dversion=1.0-SNAPSHOT \
-DpackageName=com.yourpackage.sample.chatapp \
-DarchetypeGroupId=org.apache.maven.archetypes \
-DarchetypeArtifactId=maven-archetype-webapp \
-DarchetypeVersion=1.1 \
-DinteractiveMode=false
Created in this way, the project can be then imported into your IDE, for example by using fallowing command: mvn idea:idea (for IntelliJ Idea).
The next step is to modify generated pom.xml file to include Bristleback Framework dependencies.
In <dependencies></dependencies> section add:
<dependency>
<groupId>pl.bristleback</groupid>
<artifactId>bristleback-core</artifactid>
<version>0.3.5</version>
</dependency>
<dependency>
<groupId>pl.bristleback</groupid>
<artifactId>serialization-engine-jackson</artifactid>
<version>0.3.5</version>
</dependency>
Bristleback uses Spring Framework, so it's necessary to add Spring dependencies as well:
<dependency>
<groupId>org.springframework</groupid>
<artifactId>spring-context</artifactid>
<version>${org.springframework.version}</version>
</dependency>
<dependency>
<groupId>org.springframework</groupid>
<artifactId>spring-webmvc</artifactid>
<version>${org.springframework.version}</version>
</dependency>
Replace ${org.springframework.version} placeholder with the version you would like to use, we support versions 3.1.1.RELEASE or higher.
- If you want to use Jetty as the Websocket engine
<dependency>
<groupId>pl.bristleback</groupid>
<artifactId>websocket-engine-jetty</artifactid>
<version>0.3.5</version>
</dependency>
- If you want to use Apache Tomcat as the Websocket engine
<dependency>
<groupId>pl.bristleback</groupid>
<artifactId>websocket-engine-tomcat</artifactid>
<version>0.3.5</version>
</dependency>
- If you want to use Apache Tomcat as the Websocket engine
<dependency>
<groupId>pl.bristleback</groupid>
<artifactId>websocket-engine-tomcat</artifactid>
<version>0.3.5</version>
</dependency>
In this sample we use Jetty as our Websocket Engine. Jetty provides nice Maven plugin for fast web application running. Following step isn't necessary in most environments, but in some cases prevents Maven from using wrong version of the Jetty plugin. Put this code in <build></build> section:
<pluginManagement>
<plugins>
<plugin>
<groupId>org.mortbay.jetty</groupid>
<artifactId>jetty-maven-plugin</artifactid>
<version>8.1.10.v20130312</version>
</plugin>
</plugins>
</pluginmanagement>
Then we create applicationContext.xml file, in which whole Bristleback configuration will be placed. Go to the src/main/webapp/WEB-INF directory, this is the place where applicationContext.xml file should be placed. The content of this file is presented below:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:bb="http://www.bristleback.pl/schema/bristleback"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context-2.5.xsd
http://www.bristleback.pl/schema/bristleback
http://www.bristleback.pl/schema/bristleback/bristleback.xsd">
<context:component-scan base-package="com.yourpackage.sample.chatapp"/>
<bb:serverMessages/>
<bean id="pojoConfigResolver" class="pl.bristleback.server.bristle.conf.resolver.init.PojoConfigResolver">
<property name="engineName" value="system.engine.jetty.servlet"/>
</bean>
<bb:servlet configurationResolver="pojoConfigResolver"/>
</beans>
If you use different server engine than standalone Jetty, first thing you need to change in your configuration is a name of server engine, for example:
<bean id="pojoConfigResolver" class="pl.bristleback.server.bristle.conf.resolver.init.PojoConfigResolver">
<property name="engineName" value="system.engine.tomcat.servlet"/>
</bean>
Above sample configuration will point Bristleback to use Tomcat Servlet engine to serve as the Websocket protocol implementation. You can find more information about server engines configuration in chapter Configuration - deeper look.
By default, Maven web application archetype doesn't create main/java/${package/ directory, so to avoid errors in Spring component scanning, create such package or remove component-scan line from application context.
Another thing to do is to modify src/main/webapp/WEB-INF/web.xml descriptor file. We'll add a Spring Dispatcher Servlet:
<?xml version="1.0" encoding="UTF-8"?>
<web-app
version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
<display-name>Bristleback Web Application</display-name>
<servlet>
<servlet-name>springServlet</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<init-param>
<param-name>contextConfigLocation</param-name>
<param-value>WEB-INF/applicationContext.xml</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>springServlet</servlet-name>
<url-pattern>/websocket/*</url-pattern>
</servlet-mapping>
</web-app>
Bristleback <bb:servlet> tag creates default handler mappings for Dispatcher Servlet (with mapping key: **/* - all requests within Spring Dispatcher Servlet will be handled by Bristleback Http handler), but you are free to define custom mappings by providing reference to your mappings bean, for example:
<bean id="customMappings" class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
<property name="mappings">
<map>
<entry key="/dd" value-ref="bristlebackHttpHandler"/>
</map>
</property>
</bean>
<bb:servlet configurationResolver="pojoConfigResolver" handlerMappings="customMappings"/>
Although server is ready to be run, we need to edit generated src/main/webapp/WEB-INF/index.html page to test the connection. The page will contain two buttons for connecting/disconnecting and a status container. Required client library can be found here.
<html>
<head>
<script type="text/javascript" src="./bristleback-0.3.5.js"></script>
<script type="text/javascript">
var config = {
serverUrl: "ws://localhost:8080/websocket",
onOpen: function(event) {
document.getElementById('status').innerHTML = "The WebSocket Connection Is Open.";
},
onClose: function(event) {
document.getElementById('status').innerHTML = "The WebSocket Connection Is Closed.";
}
};
var client = Bristleback.newClient(config);
var dataController = client.dataController;
function connect() {
client.connect();
}
function closeConnection() {
client.disconnect();
}
</script>
</head>
<body>
<div id="status">Click connect button to start playing.</div>
<div>
<input type="button" onclick="connect()" value="Connect">
<input type="button" onclick="closeConnection()" value="Close connection">
</div>
</body>
</html>
Note that in web application, port on which WebSockets engine is listening is taken from web application container (engine port configuration element is ignored), both in Apache Tomcat and Jetty it is 8080 by default.
You've already seen base configuration elements in previous subsections. Without going into the details, we want to mention about few things related with configuration in Bristleback.
Special class encapsulates configuration provided by the application creator, it is pl.bristleback.server.bristle.conf.InitialConfiguration. Every element of configuration has default value(s), stored in static fields in InitialConfiguration class. InitialConfiguration initialization is done by one of pl.bristleback.server.bristle.api.InitialConfigurationResolver implementation, for example pl.bristleback.server.bristle.conf.resolver.init.PojoConfigResolver, which we used in preceding examples. Overriding default settings is pretty easy:
<bean id="pojoConfigResolver" class="pl.bristleback.server.bristle.conf.resolver.init.PojoConfigResolver">
<property name="engineName" value="system.engine.jetty.servlet"/>
</bean>
Probably the most important configuration element is the server engine component, which serves as WebSocket protocol implementation. In current version, you may choose from three different engines: Jetty, Netty and Tomcat. Documentation of each configuration element interfaces contains information about built in implementations.