mina-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From apali...@apache.org
Subject svn commit: r1391558 - in /mina/site/trunk: content/vysper/ templates/vysper/
Date Fri, 28 Sep 2012 17:11:52 GMT
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">&quot;vysper.org&quot;</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">&quot;vysper.org&quot;</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">&quot;keystore.jks&quot;</SPAN>), <SPAN class="code-quote">&quot;sekrit&quot;</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(&ldquo;vysper.org&rdquo;);
+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(&ldquo;proxy&rdquo;));
+</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(&ldquo;proxy&rdquo;,
<SPAN class="code-keyword">new</SPAN> InetSocketAddress(&ldquo;foo.vysper.org&rdquo;,
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(&ldquo;proxy&rdquo;,
<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 {
+    &#64;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&lt;<SPAN class="code-object">String</SPAN>, <SPAN class="code-object">String</SPAN>&gt;
env = <SPAN class="code-keyword">new</SPAN> Hashtable&lt;<SPAN class="code-object">String</SPAN>,
<SPAN class="code-object">String</SPAN>&gt;();
+		env.put(Context.INITIAL_CONTEXT_FACTORY, <SPAN class="code-quote">&quot;com.sun.jndi.ldap.LdapCtxFactory&quot;</SPAN>);
+		env.put(Context.PROVIDER_URL, <SPAN class="code-quote">&quot;ldap:<SPAN class="code-comment">//localhost:389/&quot;</SPAN>);
+</SPAN>
+		env.put(Context.SECURITY_AUTHENTICATION, <SPAN class="code-quote">&quot;simple&quot;</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">&quot;cn=%s, ou=Users, o=Acme&quot;</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">&quot;acme.com&quot;</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">&quot;vysper.org&quot;</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">&quot;/xmpp&quot;</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">&quot;keystore.jks&quot;</SPAN>,
<SPAN class="code-quote">&quot;sekrit&quot;</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">
+&lt;servlet&gt;
+  &lt;servlet-name&gt;WebSocket Servlet&lt;/servlet-name&gt;
+  &lt;servlet-class&gt;org.apache.vysper.xmpp.extension.websockets.TomcatXmppWebSocketServlet&lt;/servlet-class&gt;
+  &lt;load-on-startup&gt;1&lt;/load-on-startup&gt;
+&lt;/servlet&gt;
+&lt;servlet-mapping&gt;
+  &lt;servlet-name&gt;WebSocket Servlet&lt;/servlet-name&gt;
+  &lt;url-pattern&gt;/ws&lt;/url-pattern&gt;
+&lt;/servlet-mapping&gt;
+</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" %}



Mime
View raw message