You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mina.apache.org by ap...@apache.org on 2012/09/28 19:11:52 UTC
svn commit: r1391558 - in /mina/site/trunk: content/vysper/ templates/vysper/
Author: apaliwal
Date: Fri Sep 28 17:11:51 2012
New Revision: 1391558
URL: http://svn.apache.org/viewvc?rev=1391558&view=rev
Log:
vysper pages initial batch
Added:
mina/site/trunk/content/vysper/
mina/site/trunk/content/vysper/documentation.mdtext
mina/site/trunk/content/vysper/index.mdtext
mina/site/trunk/content/vysper/server_to_server_comm.mdtext
mina/site/trunk/content/vysper/socks5.mdtext
mina/site/trunk/content/vysper/stanza_processing_layer.mdtext
mina/site/trunk/content/vysper/user_mgmt.mdtext
mina/site/trunk/content/vysper/websocket_endpoint.mdtext
mina/site/trunk/content/vysper/xml_processing.mdtext
mina/site/trunk/templates/vysper/page.html
Added: mina/site/trunk/content/vysper/documentation.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/vysper/documentation.mdtext?rev=1391558&view=auto
==============================================================================
--- mina/site/trunk/content/vysper/documentation.mdtext (added)
+++ mina/site/trunk/content/vysper/documentation.mdtext Fri Sep 28 17:11:51 2012
@@ -0,0 +1,50 @@
+Title: Documentation
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+## What is it?
+
+Apache Vysper aims to be a full blown [XMPP](http://www.xmpp.org/) (=eXtensible Messaging and Presence Protocol) server.
+The core of XMPP is defined in the standards [RFC3920](http://www.ietf.org/rfc/rfc3920.txt) and [RFC3921](http://www.ietf.org/rfc/rfc3921.txt).
+
+XMPP is more commonly known as 'Jabber'.
+
+## XMPP Specifications
+
+A list of the implementation status of the various specifications are available.
+
+## Architecture
+
+XML Processing
+Stanza processing
+User authentication and management
+
+## Using the server
+
+Apache Vysper can run stand-alone or embedded into another application.
+It should work with any compliant XMPP client.
+A test client is included with the project.
+
+## Modules/endpoints
+
+Here you can find documentation for using some of the Vysper extensions. Modules usually implement different XEP specifications, while Endpoints implement network protocols.
+
+Server-to-server connections
+SOCKS5 bytestream module
+Websockets endpoint
+
+
Added: mina/site/trunk/content/vysper/index.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/vysper/index.mdtext?rev=1391558&view=auto
==============================================================================
--- mina/site/trunk/content/vysper/index.mdtext (added)
+++ mina/site/trunk/content/vysper/index.mdtext Fri Sep 28 17:11:51 2012
@@ -0,0 +1,33 @@
+Title: Apache Vysper
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+
+# Apache Vysper
+
+Apache Vysper aims to be a modular, full featured XMPP (Jabber) server.
+
+More details on Vysper in our documentation.
+
+There are already some larger XEPs as modules available, most notably
+
+* Multi User Chat ([XEP0045](http://xmpp.org/extensions/xep-0045.html)) and
+* Publish/Subscribe ([XEP0060](http://xmpp.org/extensions/xep-0060.html))
+* BOSH ([XEP0124](http://xmpp.org/extensions/xep-0124.html), [XEP0206](http://xmpp.org/extensions/xep-0206.html))
+
+To start using and/or developing extensions for Vysper, don't miss the User Guide!
+
Added: mina/site/trunk/content/vysper/server_to_server_comm.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/vysper/server_to_server_comm.mdtext?rev=1391558&view=auto
==============================================================================
--- mina/site/trunk/content/vysper/server_to_server_comm.mdtext (added)
+++ mina/site/trunk/content/vysper/server_to_server_comm.mdtext Fri Sep 28 17:11:51 2012
@@ -0,0 +1,71 @@
+Title: Server-to-server
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+
+# Server-to-server
+
+<DIV class="panelMacro"><TABLE class="infoMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>Available since version 0.7.</TD></TR></TABLE></DIV>
+
+XMPP servers like Apache Vysper work in federated networks much like SMTP servers. Users connect to their own server, and when communicating with users on a different domain, the two servers will connect to each other and exchange XMPP stanzas. Server-to-server (S2S) connections differ from client-to-server (C2) connections in that stanzas for multiple users might be sent over the same connection. S2S connections are similar to C2S connections from the point that one of the servers serves as an initiator, like a client. To exchanges stanzas in both directions between servers, two connections are established.
+
+To set up server-to-server functionality in Vysper, two configurations are needed:
+
+## Allow server-to-server federation
+
+Server-to-server federation is by default disabled in Vysper. To enable sending stanzas to other servers, federations must be enabled:
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+XMPPServer server = <SPAN class="code-keyword">new</SPAN> XMPPServer(<SPAN class="code-quote">"vysper.org"</SPAN>);
+
+<SPAN class="code-comment">// other initialization
+</SPAN>
+server.start();
+
+<SPAN class="code-comment">// must be done after the server has been started
+</SPAN>server.getServerRuntimeContext().getServerFeatures().setRelayingToFederationServers(<SPAN class="code-keyword">true</SPAN>);
+</PRE>
+</DIV></DIV>
+
+## Server-to-server endpoint
+
+Next, an endpoint for incoming S2S connections must be added:
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+XMPPServer server = <SPAN class="code-keyword">new</SPAN> XMPPServer(<SPAN class="code-quote">"vysper.org"</SPAN>);
+
+server.addEndpoint(<SPAN class="code-keyword">new</SPAN> S2SEndpoint());
+
+<SPAN class="code-comment">// other initialization
+</SPAN>
+server.start();
+
+<SPAN class="code-comment">// must be done after the server has been started
+</SPAN>server.getServerRuntimeContext().getServerFeatures().setRelayingToFederationServers(<SPAN class="code-keyword">true</SPAN>);
+</PRE>
+</DIV></DIV>
+
+Thatâs all that needs to be done. If SSL/TLS should be enabled between servers (will be negotiated during the S2S connection handshake), a keystore and keystore password must be configured:
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+server.setTLSCertificateInfo(<SPAN class="code-keyword">new</SPAN> File(<SPAN class="code-quote">"keystore.jks"</SPAN>), <SPAN class="code-quote">"sekrit"</SPAN>);
+
+</PRE>
+</DIV></DIV>
Added: mina/site/trunk/content/vysper/socks5.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/vysper/socks5.mdtext?rev=1391558&view=auto
==============================================================================
--- mina/site/trunk/content/vysper/socks5.mdtext (added)
+++ mina/site/trunk/content/vysper/socks5.mdtext Fri Sep 28 17:11:51 2012
@@ -0,0 +1,73 @@
+Title: SOCKS5 bytestream module
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+
+# SOCKS5 bytestream module
+
+<DIV class="panelMacro"><TABLE class="infoMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>Available since version 0.7.</TD></TR></TABLE></DIV>
+
+The Vysper SOCKS5 Bytestream module implements mediated connections from XEP-0065 SOCKS5 Bytestream. Direct connections requires no support from the server and thus works without this module. For mediated connections, this module will supply a SOCKS5 proxy that transfers data between the requestor and target clients. The module also provides all the required service discovery support used to negotiate the address of the SOCKS5 proxy.
+
+The example below shows how to add the module using the API:
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+XMPPServer server = <SPAN class="code-keyword">new</SPAN> XMPPServer(“vysper.org”);
+server.addEndpoint(<SPAN class="code-keyword">new</SPAN> TCPEndpoint());
+
+<SPAN class="code-comment">// other initialization
+</SPAN>
+server.addModule(<SPAN class="code-keyword">new</SPAN> Socks5Module());
+
+server.start();
+</PRE>
+</DIV></DIV>
+
+This will enable the SOCKS5 component on socks.vysper.org and start a proxy on port 5777. Make sure socks.vysper.org resolves to the server running Vysper.
+
+To configure the subdomain name, provide the subdomain in the constructor:
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+server.addModule(<SPAN class="code-keyword">new</SPAN> Socks5Module(“proxy”));
+</PRE>
+</DIV></DIV>
+
+In this case, the SOCKS5 component would be available on proxy.vysper.org.
+
+It is also possible to supply a socket address on which the proxy will be listening. This can be used to configure the port for the proxy, or the local address to bind the proxy to. For example:
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+server.addModule(<SPAN class="code-keyword">new</SPAN> Socks5Module(“proxy”, <SPAN class="code-keyword">new</SPAN> InetSocketAddress(“foo.vysper.org”, 18100)));
+</PRE>
+</DIV></DIV>
+
+With this code, the proxy will use the JID proxy.vysper.org, the hostname foo.vysper.org and the port 18100. It will only listen on the network interface for foo.vysper.org.
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+server.addModule(<SPAN class="code-keyword">new</SPAN> Socks5Module(“proxy”, <SPAN class="code-keyword">new</SPAN> InetSocketAddress(18100)));
+</PRE>
+</DIV></DIV>
+
+n this case, the proxy will use the JID and hostname proxy.vysper.org and the port 18100. It will listen on all network interfaces.
+
+## Limitations
+
+The module currently only supports unauthenticated SOCKS5 connections (support for username/password connections is tracked in [VYSPER-280](https://issues.apache.org/jira/browse/VYSPER-280)).
Added: mina/site/trunk/content/vysper/stanza_processing_layer.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/vysper/stanza_processing_layer.mdtext?rev=1391558&view=auto
==============================================================================
--- mina/site/trunk/content/vysper/stanza_processing_layer.mdtext (added)
+++ mina/site/trunk/content/vysper/stanza_processing_layer.mdtext Fri Sep 28 17:11:51 2012
@@ -0,0 +1,32 @@
+Title: Stanza Processing
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+
+# Stanza Processing
+
+Commands in the XMPP world are called Stanzas.
+
+At the transport layer, when going over the net between client and server, they have a textual representation in XML.
+
+In Vysper, the Stanza processing layer only deals with Stanza java objects. They are created by the transport layer, or using Builder utility classes from within Vysper. That makes this layer independent from any underlying transport layer. Stanzas are directly injectable on this level. This helps when testing. It makes accessing specific stanza elements easier.
+
+Every Stanza is processed in the context of a Session and a Server. The general approach is comparable to the Servlet architecture.
+A Session has a state which indicates how far the process of stream negotiation has advanced. The protocol worker determines that the incoming stanza can be processed, depending on the session state. Otherwise, an stream error is returned. For example, Message stanzas can only be compliantly processed after the session is bound to a resource.
+
+In the next step, the protocol worker searches for the right Stanza Handler. This often requires inspecting the Stanza,
+The handler incorporates the actual command execution logic.
Added: mina/site/trunk/content/vysper/user_mgmt.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/vysper/user_mgmt.mdtext?rev=1391558&view=auto
==============================================================================
--- mina/site/trunk/content/vysper/user_mgmt.mdtext (added)
+++ mina/site/trunk/content/vysper/user_mgmt.mdtext Fri Sep 28 17:11:51 2012
@@ -0,0 +1,94 @@
+Title: User Management
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+
+# User Management
+
+Apache Vysper comes with very basic user management support out of the box. But, frequently you would rather want to integrate Vysper with your already existing authentication solution. To enable this, Vysper comes with a simple API to implement your own authentication and user management.
+
+## Authentication
+
+UserAuthentication is the interface which will get called when a client authenticates itself using SASL. Vysper currently ships with two implementations, one in-memory and one based on JCR. To write your own, simple create a class which implements UserAuthentication. In the example below, we implement an authentication provider backed by an LDAP directory.
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-keyword">public</SPAN> class MyLdapAuthentication <SPAN class="code-keyword">implements</SPAN> UserAuthentication {
+ @Override
+ <SPAN class="code-keyword">public</SPAN> <SPAN class="code-object">boolean</SPAN> verifyCredentials(Entity jid, <SPAN class="code-object">String</SPAN> passwordCleartext, <SPAN class="code-object">Object</SPAN> credentials) {
+ Hashtable<<SPAN class="code-object">String</SPAN>, <SPAN class="code-object">String</SPAN>> env = <SPAN class="code-keyword">new</SPAN> Hashtable<<SPAN class="code-object">String</SPAN>, <SPAN class="code-object">String</SPAN>>();
+ env.put(Context.INITIAL_CONTEXT_FACTORY, <SPAN class="code-quote">"com.sun.jndi.ldap.LdapCtxFactory"</SPAN>);
+ env.put(Context.PROVIDER_URL, <SPAN class="code-quote">"ldap:<SPAN class="code-comment">//localhost:389/"</SPAN>);
+</SPAN>
+ env.put(Context.SECURITY_AUTHENTICATION, <SPAN class="code-quote">"simple"</SPAN>);
+
+ // extract the user name from the entity, e.g. from foo@example.com, foo will be used
+ env.put(Context.SECURITY_PRINCIPAL, <SPAN class="code-object">String</SPAN>.format(<SPAN class="code-quote">"cn=%s, ou=Users, o=Acme"</SPAN>, jid.getNode()));
+ env.put(Context.SECURITY_CREDENTIALS, passwordCleartext);
+
+ try {
+ // connect and authenticate with the directory
+ new InitialDirContext(env);
+ return true;
+ } <SPAN class="code-keyword">catch</SPAN> (NamingException e) {
+ <SPAN class="code-keyword">return</SPAN> <SPAN class="code-keyword">false</SPAN>;
+ }
+ }
+}
+</PRE>
+</DIV></DIV>
+
+Next, you need to hook the authentication provider into the Vysper XMPP server:
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+ <SPAN class="code-keyword">public</SPAN> <SPAN class="code-keyword">static</SPAN> void main(<SPAN class="code-object">String</SPAN>[] args) <SPAN class="code-keyword">throws</SPAN> Exception {
+ OpenStorageProviderRegistry providerRegistry = <SPAN class="code-keyword">new</SPAN> OpenStorageProviderRegistry();
+
+ <SPAN class="code-comment">// add your custom authentication provider
+</SPAN> providerRegistry.add(<SPAN class="code-keyword">new</SPAN> MyLdapAuthentication());
+
+ <SPAN class="code-comment">// a roster manager is also required
+</SPAN> providerRegistry.add(<SPAN class="code-keyword">new</SPAN> MemoryRosterManager());
+
+ XMPPServer server = <SPAN class="code-keyword">new</SPAN> XMPPServer(<SPAN class="code-quote">"acme.com"</SPAN>);
+
+ <SPAN class="code-comment">// other initialization
+</SPAN> <SPAN class="code-comment">// ...
+</SPAN>
+ server.setStorageProviderRegistry(providerRegistry);
+
+ server.start();
+ }
+</PRE>
+</DIV></DIV>
+
+In this example, we use the OpenStorageProviderRegistry to provide the different storage providers. Only two are required, UserAuthentication and RosterManager.
+
+That's all that's needed to implement a custom authentication provider.
+
+## User management
+
+Some Vysper modules, in particular in-band registration and service administration, requires the ability to add users and change users password. For that, Vysper uses the interface AccountManagement. This interface has three methods:
+
+* addUser(username, password): to add a new user
+* changePassword(username, newPassword): to change the password of a user
+* verifyAccountExists(username): checks if a user exists
+
+If you need to make use of any of these modules, provide an AccountManagement implementation in OpenStorageProviderRegistry as in the example above.
+
+
Added: mina/site/trunk/content/vysper/websocket_endpoint.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/vysper/websocket_endpoint.mdtext?rev=1391558&view=auto
==============================================================================
--- mina/site/trunk/content/vysper/websocket_endpoint.mdtext (added)
+++ mina/site/trunk/content/vysper/websocket_endpoint.mdtext Fri Sep 28 17:11:51 2012
@@ -0,0 +1,88 @@
+Title: Websocket endpoint
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+
+# Websocket endpoint
+
+<DIV class="panelMacro"><TABLE class="infoMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>Available since version 0.7.</TD></TR></TABLE></DIV>
+
+While websockets are still being specified, a draft specification for XMPP over websockets has been published at <http://tools.ietf.org/html/draft-moffitt-xmpp-over-websocket-00>. Websockets enables web browsers to establish duplex communications with servers with very little overhead.
+
+Vysper provides a websocket endpoint. The easiest way to use the endpoint is to simply add it as a regular endpoint:
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+XMPPServer server = <SPAN class="code-keyword">new</SPAN> XMPPServer(<SPAN class="code-quote">"vysper.org"</SPAN>);
+
+server.addEndpoint(<SPAN class="code-keyword">new</SPAN> TCPEndpoint());
+
+server.addEndpoint(<SPAN class="code-keyword">new</SPAN> WebSocketEndpoint());
+
+<SPAN class="code-comment">// other initialization
+</SPAN>
+server.start();
+</PRE>
+</DIV></DIV>
+
+Thatâs it. The default configuration will start a web server on port 8080 and supply websockets on <http://vysper.org:8080/>.
+
+The port and context path can be configured:
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+WebSocketEndpoint wsEndpoint = <SPAN class="code-keyword">new</SPAN> WebSocketEndpoint();
+wsEndpoint.setContextPath(<SPAN class="code-quote">"/xmpp"</SPAN>);
+wsEndpoint.setPort(9000);
+server.addEndpoint(wsEndpoint);
+</PRE>
+</DIV></DIV>
+
+## Embedded
+
+Commonly, thereâs a need to use websockets within the context of a web application. For that purpose, there is a servlet available that can be configured in web.xml inside your regular application.
+
+Vysper currently supports this for Jetty and Apache Tomcat 7.0.27 or later.
+
+For Jetty, add the following to your web.xml:
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+WebSocketEndpoint wsEndpoint = <SPAN class="code-keyword">new</SPAN> WebSocketEndpoint();
+wsEndpoint.setSSLEnabled(<SPAN class="code-keyword">true</SPAN>);
+wsEndpoint.setSSLCertificateKeystore(<SPAN class="code-quote">"keystore.jks"</SPAN>, <SPAN class="code-quote">"sekrit"</SPAN>);
+server.addEndpoint(wsEndpoint);
+</PRE>
+</DIV></DIV>
+
+For Tomcat, add the following to your web.xml:
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<servlet>
+ <servlet-name>WebSocket Servlet</servlet-name>
+ <servlet-class>org.apache.vysper.xmpp.extension.websockets.TomcatXmppWebSocketServlet</servlet-class>
+ <load-on-startup>1</load-on-startup>
+</servlet>
+<servlet-mapping>
+ <servlet-name>WebSocket Servlet</servlet-name>
+ <url-pattern>/ws</url-pattern>
+</servlet-mapping>
+</PRE>
+</DIV></DIV>
+
+Also, when using the servlet, the main Vysper XMPP server needs to be started by some other mean, typically via a context listener. The ServerRuntimeContext of the Vysper server needs to be made available within the servlet context under the key âorg.apache.vysper.xmpp.server.ServerRuntimeContextâ. Thereâs an example application included in the Vysper distribution which does this. The source code is available here: <http://svn.apache.org/repos/asf/mina/vysper/trunk/examples/embedded-war/>
Added: mina/site/trunk/content/vysper/xml_processing.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/vysper/xml_processing.mdtext?rev=1391558&view=auto
==============================================================================
--- mina/site/trunk/content/vysper/xml_processing.mdtext (added)
+++ mina/site/trunk/content/vysper/xml_processing.mdtext Fri Sep 28 17:11:51 2012
@@ -0,0 +1,33 @@
+Title: XM Processing
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+
+# XML Processing
+
+XML data is the payload of the XMPP protocol. More precisely, XMPP only works on a subset of XML. See RFC3920 for details.
+
+The core handler and protocol code does not deal with xml strings directly. They only deal with java objects representing well-formed XMPP commands, called stanzas.
+
+To create these objects, the actual XML is processed in stages at the xml processing layer.
+
+While raw XML continues streaming in, we are faced with arbitrary partitioned stanza and even partial xml. We have to determine the end of a stanza to process it.
+A stanza can go over multiple lines so the line end is not a useful indicator for command boundaries. We have to check for the stanza's closing element.
+
+What we do is every time new characters arrive in the character stream, we cut what we got into two kinds of fragments, those starting with < and ending with >, and those containing all the characters in between > and <. These fragments are analyzed if they could result in balanced xml. If not, we wait for more data to come.
+
+At the next stage, fragments are more extensively parsed and if everything works out fine, a Stanza java object is constructed from it and forwarded to the [stanza processing layer](stanza_processing_layer.html).
Added: mina/site/trunk/templates/vysper/page.html
URL: http://svn.apache.org/viewvc/mina/site/trunk/templates/vysper/page.html?rev=1391558&view=auto
==============================================================================
--- mina/site/trunk/templates/vysper/page.html (added)
+++ mina/site/trunk/templates/vysper/page.html Fri Sep 28 17:11:51 2012
@@ -0,0 +1,11 @@
+{% extends "header.html" %}
+ {% block css %}
+ <link href="{{base}}css/common.css" rel="stylesheet" type="text/css">
+ <link href="{{base}}css/mina.css" rel="stylesheet" type="text/css">
+ {% endblock %}
+{% endextends %}
+
+{% block content %}{{ content|markdown }}{% endblock %}
+{{ headers.test }}
+
+{% include "footer.html" %}