Author: dkatayev Date: 2010-08-05 10:37:10 -0400 (Thu, 05 Aug 2010) New Revision: 2887 Removed: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/central-authentication-service-configuration.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/cometd-cluster-bench.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/cometd-cluster.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/cometd.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/introduction-to-rest.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/javascript-webdav-library.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/kerberos-sso-on-active-directory.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/oauth.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/rest-migration-to-jsr311.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/soap-service-tutorial.xml Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws.xml Log: EXOJCR-870 WS documentation cleaned up Deleted: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/central-authentication-service-configuration.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/central-authentication-service-configuration.xml 2010-08-05 13:44:26 UTC (rev 2886) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/central-authentication-service-configuration.xml 2010-08-05 14:37:10 UTC (rev 2887) @@ -1,442 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="WS.CentralAuthenticationServiceConfiguration"> - <?dbhtml filename="ch-central-authentication-service-configuration.html"?> - - <title>Central Authentication Service Configuration</title> - - <section> - <title>Introduction</title> - - <para>Central Authentication Service (CAS) is a Web Single Sign-On - (WebSSO), developped by JA-SIG as an open-source project. CAS, like any - WebSSO, is very interesting in information systems where many applications - share a common users repository. When you enable CAS on all the - application, a user would log once and only once and will be recognized - and authentified into all the applications.</para> - - <para>CAS documentation explains how to configure in details any - environment, that is mainly a configuration of a Web application to - authenticate itself against the CAS Server instead of an internal - mechanism. This documentation explain how to configure eXo Platform to - delegate the authentication to the CAS server and let it ensure the - single-sign-one between all the applications of an IS.</para> - </section> - - <section> - <title>CAS configuration</title> - - <para>This article try to explain how to configure CAS server and client - for exo. For this example we will use 2 the same tomcat instance, but one - for it has additation CAS server.</para> - - <para>This configuration is not very useful, but very good example for - configuration CAS.</para> - - <para>Tomcat 1 deployed on windows 2003 - this is CAS server, tomcat 2 on - Ubuntu 7.10.</para> - - <section> - <title>Configure CAS server</title> - - <para><command>(DNS name: test01-srv.exoua-int)</command></para> - - <para>1.Certificates.</para> - - <programlisting>E:/Program Files&gt;cd java -E:/Program Files/Java&gt;cd jre1.5.0_11 -E:/Program Files/Java/jre1.5.0_11&gt;cd bin -E:/Program Files/Java/jre1.5.0_11/bin&gt;keytool -genkey -alias tomcat -keypass 123456 -keyalg RSA -Enter keystore password: 123456 -What is your first and last name? - [Unknown]: test01-srv.exoua-int -What is the name of your organizational unit? - [Unknown]: . -What is the name of your organization? - [Unknown]: . -What is the name of your City or Locality? - [Unknown]: . -What is the name of your State or Province? - [Unknown]: . -What is the two-letter country code for this unit? - [Unknown]: UA -Is CN=test01-srv.exoua-int, OU=., O=., L=., ST=., C=UA correct? - [no]: yes - -E:/Program Files/Java/jre1.5.0_11/bin&gt;keytool -export -alias tomcat -keypass 123456 -file server.crt -Enter keystore password: 123456 -Certificate stored in file &lt;server.crt&gt;</programlisting> - - <para>This is optional, I just want to have the same password for - storage %JRE_HOME%/lib/security/cacerts.</para> - - <programlisting>E:/Program Files/Java/jre1.5.0_11/bin&gt;keytool -storepasswd -keystore ../lib/security/cacerts -Enter keystore password: changeit -New keystore password: 123456 -Re-enter new keystore password: 123456</programlisting> - - <para>Continue with certificates.</para> - - <programlisting>E:/Program Files/Java/jre1.5.0_11/bin&gt;keytool -import -file server.crt -keypass 123456 -keystore ../lib/security/cacerts -Enter keystore password: 123456 -Owner: CN=test01-srv.exoua-int, OU=., O=., L=., ST=., C=UA -Issuer: CN=test01-srv.exoua-int, OU=., O=., L=., ST=., C=UA -Serial number: 4810c6c5 -Valid from: Fri Apr 24 20:33:36 HST 2008 until: Thu Jul 23 20:33:36 HST 2008 -Certificate fingerprints: -MD5: CC:3B:FB:FB:AE:12:AD:FB:3E:D 5:98:CB:2E:3B:0A:AD -SHA1: A1:16:80:68:39:C7:58:EA:2F:48:59:AA:1D:73:5F:56:78:CE:A4:CE -Trust this certificate? [no]: yes -Certificate was added to keystore - -E:/Program Files/Java/jre1.5.0_11/bin&gt;</programlisting> - - <para>2. Now edit server.xml file for tomcat (we are using 6.0.13 - everywhere).Uncomment configuration for SSL connection end edit it, it - must looks as this:</para> - - <programlisting>&lt;Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" -maxThreads="150" scheme="https" secure="true" -clientAuth="false" sslProtocol="TLS" -keystoreFile="E:/Documents and Settings/admin/.keystore" -keystorePass="123456" -keyAlias="tomcat" -truststoreFile="E:/Program Files/Java/jre1.5.0_11/lib/security/cacerts" -truststorePass="123456" /&gt;</programlisting> - - <para>3. Now configure client part of CAS, as example we will use - portal/private/* .Edit file /portal/WEB-INF/web.xml.</para> - - <programlisting>&lt;context-param&gt; - &lt;param-name&gt;serverName&lt;/param-name&gt; - &lt;param-value&gt;http://test01-srv.exoua-int:8080&lt;/param-value&gt; -&lt;/context-param&gt;</programlisting> - - <para>Configure client, in this example we will protect - /portal/private/* resource. Note: These filter must be add before this - filter "SetCurrentIdentityFilter", the same think for - filter-mapping.</para> - - <programlisting>&lt;filter&gt; - &lt;filter-name&gt;SingleSignOutFilter&lt;/filter-name&gt; - &lt;filter-class&gt;org.jasig.cas.client.session.SingleSignOutFilter&lt;/filter-class&gt; -&lt;/filter&gt; -&lt;filter&gt; - &lt;filter-name&gt;AuthenticationFilter&lt;/filter-name&gt; - &lt;filter-class&gt;org.jasig.cas.client.authentication.AuthenticationFilter&lt;/filter-class&gt; - &lt;init-param&gt; - &lt;param-name&gt;casServerLoginUrl&lt;/param-name&gt; - &lt;param-value&gt;https://test01-srv.exoua-int:8443/cas/login&lt;/param-value&gt; - &lt;/init-param&gt; -&lt;/filter&gt; -&lt;filter&gt; - &lt;filter-name&gt;Cas20ProxyReceivingTicketValidationFilter&lt;/filter-name&gt; - &lt;filter-class&gt;org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter&lt;/filter-class&gt; - &lt;init-param&gt; - &lt;param-name&gt;casServerUrlPrefix&lt;/param-name&gt; - &lt;param-value&gt;https://test01-srv.exoua-int:8443/cas&lt;/param-value&gt; - &lt;/init-param&gt; - &lt;init-param&gt; - &lt;param-name&gt;redirectAfterValidation&lt;/param-name&gt; - &lt;param-value&gt;true&lt;/param-value&gt; - &lt;/init-param&gt; -&lt;/filter&gt; -&lt;filter&gt; - &lt;filter-name&gt;HttpServletRequestWrapperFilter&lt;/filter-name&gt; - &lt;filter-class&gt;org.jasig.cas.client.util.HttpServletRequestWrapperFilter&lt;/filter-class&gt; -&lt;/filter&gt; -&lt;!-- eXo --&gt; -&lt;filter&gt; - &lt;filter-name&gt;BaseIdentityInitializerFilterImpl&lt;/filter-name&gt; - &lt;filter-class&gt;org.exoplatform.services.security.cas.client.impl.BaseIdentityInitializerFilterImpl&lt;/filter-class&gt; -&lt;/filter&gt; -&lt;!-- end exo --&gt; -.... -&lt;filter-mapping&gt; - &lt;filter-name&gt;SingleSignOutFilter&lt;/filter-name&gt; - &lt;url-pattern&gt;/private/*&lt;/url-pattern&gt; -&lt;/filter-mapping&gt; -&lt;filter-mapping&gt; - &lt;filter-name&gt;AuthenticationFilter&lt;/filter-name&gt; - &lt;url-pattern&gt;/private/*&lt;/url-pattern&gt; -&lt;/filter-mapping&gt; -&lt;filter-mapping&gt; - &lt;filter-name&gt;Cas20ProxyReceivingTicketValidationFilter&lt;/filter-name&gt; - &lt;url-pattern&gt;/private/*&lt;/url-pattern&gt; -&lt;/filter-mapping&gt; -&lt;filter-mapping&gt; - &lt;filter-name&gt;HttpServletRequestWrapperFilter&lt;/filter-name&gt; - &lt;url-pattern&gt;/private/*&lt;/url-pattern&gt; -&lt;/filter-mapping&gt; -&lt;!-- exo --&gt; -&lt;filter-mapping&gt; - &lt;filter-name&gt;BaseIdentityInitializerFilterImpl&lt;/filter-name&gt; - &lt;url-pattern&gt;/private/*&lt;/url-pattern&gt; -&lt;/filter-mapping&gt; -&lt;!-- end exo --&gt; -.... -&lt;listener&gt; - &lt;listener-class&gt;org.jasig.cas.client.session.SingleSignOutHttpSessionListener&lt;/listener-class&gt; -&lt;/listener&gt; -.... -&lt;!-- exo --&gt; -&lt;servlet&gt; - &lt;servlet-name&gt;LogoutServlet&lt;/servlet-name&gt; - &lt;servlet-class&gt;org.exoplatform.services.security.cas.client.impl.LogoutServlet&lt;/servlet-class&gt; - &lt;init-param&gt; - &lt;param-name&gt;casServerLogoutUrl&lt;/param-name&gt; - &lt;param-value&gt;https://test01-srv.exoua-int:8443/cas/logout&lt;/param-value&gt; - &lt;/init-param&gt; - &lt;init-param&gt; - &lt;param-name&gt;redirectToUrl&lt;/param-name&gt; - &lt;param-value&gt;http://test01-srv.exoua-int:8080/portal/public/classic&lt;/param-value&gt; - &lt;/init-param&gt; -&lt;/servlet&gt; -&lt;!-- end exo --&gt; -..... -&lt;!-- exo --&gt; -&lt;servlet-mapping&gt; - &lt;servlet-name&gt;LogoutServlet&lt;/servlet-name&gt; - &lt;url-pattern&gt;/logout/*&lt;/url-pattern&gt; -&lt;/servlet-mapping&gt; -&lt;!-- end exo --&gt; -....</programlisting> - - <para>4. Download and build code from <link - linkend="???">http://svn.exoplatform.org/svnroot/exoplatform... - - <para>5. Download and put cas-client-core-3.1.1.jar in - CATALINA_HOME%/lib directory.</para> - - <para>6. Download CAS server source code and build it or download - binary. Put cas.war in webapps directoryChange configuration in file - /cas/WEB-INF/deployConfigContext.xml. Comment test authenticator and add - new one.</para> - - <programlisting>&lt;!-- -&lt;bean class="org.jasig.cas.authentication.handler.support.SimpleTestUsernamePasswordAuthenticationHandler" /&gt; ---&gt; -&lt;!-- will check username and password at remote host --&gt; -&lt;bean class="org.exoplatform.services.security.cas.server.HTTPAuthenticationHandler" -p:authenticationURL="https://ubu.exoua-int:8443/portal/login" /&gt;</programlisting> - - <para>7. Download and build code which can do remote - authentication.Download and build code from <link - linkend="???">http://svn.exoplatform.org/svnroot/exoplatform...;, - andput it cas/WEB-INF/lib directory. This CAS server side handler which - can call remote eXo authenticatiob service via HTTP.In this case - validation of username/password wiil be done at ubu.exoua-int, but - authentication sever (CAS) will be at test01-srv.exoua-int</para> - </section> - - <section> - <title>Configure other tomcat instance</title> - - <para><command>Configure other tomcat instance, deploy it on Ubuntu 7.10 - (DNS name: ubu.exoua-int).</command></para> - - <para>1. Generate certificates for CAS client. The same as for previous - but change name to ubu.exoua-int.</para> - - <para>2. Edit server.xml file for tomcat.</para> - - <programlisting>&lt;Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" -maxThreads="150" scheme="https" secure="true" -clientAuth="false" sslProtocol="TLS" -keystoreFile="/home/andrew/.keystore" -keystorePass="123456" -keyAlias="tomcat" -truststoreFile="/home/andrew/lib/java/jre/lib/security/cacerts" -truststorePass="123456" /&gt;</programlisting> - - <para>3. Edit file portal/WEB-INF/web.xml, add next strings in it. - Change context parameter.</para> - - <programlisting>&lt;context-param&gt; - &lt;param-name&gt;serverName&lt;/param-name&gt; - &lt;param-value&gt;http://ubu.exoua-int:8080&lt;/param-value&gt; -&lt;/context-param&gt;</programlisting> - - <para>Filters configuration must be the same as in client part on - tomcat1. But add one more servlet which will check - username/password.</para> - - <programlisting>&lt;filter&gt; - &lt;filter-name&gt;SingleSignOutFilter&lt;/filter-name&gt; - &lt;filter-class&gt;org.jasig.cas.client.session.SingleSignOutFilter&lt;/filter-class&gt; -&lt;/filter&gt; -&lt;filter&gt; - &lt;filter-name&gt;AuthenticationFilter&lt;/filter-name&gt; - &lt;filter-class&gt;org.jasig.cas.client.authentication.AuthenticationFilter&lt;/filter-class&gt; - &lt;init-param&gt; - &lt;param-name&gt;casServerLoginUrl&lt;/param-name&gt; - &lt;param-value&gt;https://test01-srv.exoua-int:8443/cas/login&lt;/param-value&gt; - &lt;/init-param&gt; -&lt;/filter&gt; -&lt;filter&gt; - &lt;filter-name&gt;Cas20ProxyReceivingTicketValidationFilter&lt;/filter-name&gt; - &lt;filter-class&gt;org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter&lt;/filter-class&gt; - &lt;init-param&gt; - &lt;param-name&gt;casServerUrlPrefix&lt;/param-name&gt; - &lt;param-value&gt;https://test01-srv.exoua-int:8443/cas&lt;/param-value&gt; - &lt;/init-param&gt; - &lt;init-param&gt; - &lt;param-name&gt;redirectAfterValidation&lt;/param-name&gt; - &lt;param-value&gt;true&lt;/param-value&gt; - &lt;/init-param&gt; -&lt;/filter&gt; -&lt;filter&gt; - &lt;filter-name&gt;HttpServletRequestWrapperFilter&lt;/filter-name&gt; - &lt;filter-class&gt;org.jasig.cas.client.util.HttpServletRequestWrapperFilter&lt;/filter-class&gt; -&lt;/filter&gt; -&lt;!-- exo --&gt; -&lt;filter&gt; - &lt;filter-name&gt;BaseIdentityInitializerFilterImpl&lt;/filter-name&gt; - &lt;filter-class&gt;org.exoplatform.services.security.cas.client.impl.BaseIdentityInitializerFilterImpl\ -&lt;/filter-class&gt; -&lt;/filter&gt; -&lt;!-- end exo --&gt; -.... -&lt;filter-mapping&gt; - &lt;filter-name&gt;SingleSignOutFilter&lt;/filter-name&gt; - &lt;url-pattern&gt;/private/&amp;#42;&lt;/url-pattern&gt; -&lt;/filter-mapping&gt; -&lt;filter-mapping&gt; - &lt;filter-name&gt;AuthenticationFilter&lt;/filter-name&gt; - &lt;url-pattern&gt;/private/&amp;#42;&lt;/url-pattern&gt; -&lt;/filter-mapping&gt; -&lt;filter-mapping&gt; - &lt;filter-name&gt;Cas20ProxyReceivingTicketValidationFilter&lt;/filter-name&gt; - &lt;url-pattern&gt;/private/&amp;#42;&lt;/url-pattern&gt; -&lt;/filter-mapping&gt; -&lt;filter-mapping&gt; - &lt;filter-name&gt;HttpServletRequestWrapperFilter&lt;/filter-name&gt; - &lt;url-pattern&gt;/private/&amp;#42;&lt;/url-pattern&gt; -&lt;/filter-mapping&gt; -&lt;!-- exo --&gt; -&lt;filter-mapping&gt; - &lt;filter-name&gt;BaseIdentityInitializerFilterImpl&lt;/filter-name&gt; - &lt;url-pattern&gt;/private/&amp;#42;&lt;/url-pattern&gt; -&lt;/filter-mapping&gt; -&lt;!-- end exo --&gt; -.... -&lt;listener&gt; - &lt;listener-class&gt;org.jasig.cas.client.session.SingleSignOutHttpSessionListener&lt;/listener-class&gt; -&lt;/listener&gt; -.... -&lt;!-- exo --&gt; -&lt;servlet&gt; - &lt;servlet-name&gt;BaseHTTPUsernamePasswordValidator&lt;/servlet-name&gt; - &lt;servlet-class&gt;org.exoplatform.services.security.cas.client.impl.BaseHTTPUsernamePasswordValidatorImpl&lt;/servlet-class&gt; -&lt;/servlet&gt; -&lt;servlet&gt; - &lt;servlet-name&gt;LogoutServlet&lt;/servlet-name&gt; - &lt;servlet-class&gt;org.exoplatform.services.security.cas.client.impl.LogoutServlet&lt;/servlet-class&gt; - &lt;init-param&gt; - &lt;param-name&gt;casServerLogoutUrl&lt;/param-name&gt; - &lt;param-value&gt;https://test01-srv.exoua-int:8443/cas/logout&lt;/param-value&gt; - &lt;/init-param&gt; - &lt;init-param&gt; - &lt;param-name&gt;redirectToUrl&lt;/param-name&gt; - &lt;param-value&gt;http://ubu.exoua-int:8080/portal/public/classic&lt;/param-value&gt; - &lt;/init-param&gt; -&lt;/servlet&gt; -&lt;!-- end exo --&gt; -..... -&lt;!-- exo --&gt; -&lt;servlet-mapping&gt; - &lt;servlet-name&gt;BaseHTTPUsernamePasswordValidator&lt;/servlet-name&gt; - &lt;url-pattern&gt;/login/&amp;#42;&lt;/url-pattern&gt; -&lt;/servlet-mapping&gt; -&lt;servlet-mapping&gt; - &lt;servlet-name&gt;LogoutServlet&lt;/servlet-name&gt; - &lt;url-pattern&gt;/logout/&amp;#42;&lt;/url-pattern&gt; -&lt;/servlet-mapping&gt; -&lt;!-- end exo --&gt; -&lt;!-- not use default authentification--&gt; -&lt;!-- -&lt;security-constraint&gt; - &lt;web-resource-collection&gt; - &lt;web-resource-name&gt;user authentication&lt;/web-resource-name&gt; - &lt;url-pattern&gt;/private/&amp;#42;&lt;/url-pattern&gt; - &lt;http-method&gt;POST&lt;/http-method&gt; - &lt;http-method&gt;GET&lt;/http-method&gt; - &lt;/web-resource-collection&gt; - &lt;auth-constraint&gt; - &lt;role-name&gt;users&lt;/role-name&gt; - &lt;/auth-constraint&gt; - &lt;user-data-constraint&gt; - &lt;transport-guarantee&gt;NONE&lt;/transport-guarantee&gt; - &lt;/user-data-constraint&gt; - &lt;/security-constraint&gt; - - &lt;login-config&gt; - &lt;auth-method&gt;FORM&lt;/auth-method&gt; - &lt;realm-name&gt;exo-domain&lt;/realm-name&gt; - &lt;form-login-config&gt; - &lt;form-login-page&gt;/login/jsp/login.jsp&lt;/form-login-page&gt; - &lt;form-error-page&gt;/login/jsp/login.jsp&lt;/form-error-page&gt; - &lt;/form-login-config&gt; - &lt;/login-config&gt; - - &lt;security-role&gt; - &lt;description&gt;a simple user role&lt;/description&gt; - &lt;role-name&gt;users&lt;/role-name&gt; - &lt;/security-role&gt; - - &lt;security-role&gt; - &lt;description&gt;the admin role&lt;/description&gt; - &lt;role-name&gt;admin&lt;/role-name&gt; - &lt;/security-role&gt; ---&gt; -&lt;!-- end web.xml file--&gt; -....</programlisting> - - <para>4. Download and build code from <link - linkend="???">http://svn.exoplatform.org/svnroot/exoplatform... - - <para>5. Download and put cas-client-core-3.1.1.jar in - CATALINA_HOME%/lib directory.</para> - - <para>6. Now get trusted certificate for CAS server instance. To do this - download and compile this file: <link - linkend="???">http://blogs.sun.com/andreas/resource/InstallC... - Then run it:</para> - - <programlisting>java InstallCert test01-srv.exoua-int:8443 123456</programlisting> - - <para>Change 123456 to actual password for keystore. You can see some - exception but finally you must see info about certificates and prompt - about adding it in storage. Select certificate, usually type 1 end press - Enter.</para> - - <para>Finish!!!</para> - </section> - - <section> - <title>Usage</title> - - <para>Run both servers, and try open one of protected URLs, for example - <link - linkend="???">http://test01-srv.exoua-int:8080/portal/private/classic</link>. - Accept certificates, and in login page username/password: root/exo. You - must get private area in portal as root, then open other protected - resource on server 'ubu.exoua-int', <link - linkend="???">http://ubu.exoua-int:8080/portal/private/classic</link>. - And you must get this private area in other portal <command>without - login</command>. If you get it then SSO for login work as well.</para> - - <para>No try logout on 'ubu.exoua-int'. To do it directly from portal - one groovy script must be modified, but it is not described here.</para> - - <para>After logout from 'ubu.exoua-int' you should be asked about login - at 'test01-srv.exoua-int'. The SSO for logout work well also.</para> - - <para>That is all!</para> - - <para>If it works as described above, then configuration right and SSO - works.</para> - </section> - </section> -</chapter> Deleted: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/cometd-cluster-bench.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/cometd-cluster-bench.xml 2010-08-05 13:44:26 UTC (rev 2886) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/cometd-cluster-bench.xml 2010-08-05 14:37:10 UTC (rev 2887) @@ -1,186 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id = "WS.CometdClusterBench"> - <?dbhtml filename="ch-cometd-cluster-bench.html"?> - - <title>Cometd Cluster Bench</title> - - <section> - <title>How we test</title> - - <para>We simple open many connection, all client subscribing to one - channel, we don't send any message to client, they reconnect through - 120000 ms. Settings for cometd servlet.</para> - - <programlisting>&lt;servlet&gt; - &lt;servlet-name&gt;cometd&lt;/servlet-name&gt; - &lt;servlet-class&gt;org.mortbay.cometd.continuation.EXoContinuationCometdServlet&lt;/servlet-class&gt; - &lt;init-param&gt; - &lt;param-name&gt;filters&lt;/param-name&gt; - &lt;param-value&gt;/WEB-INF/filters.json&lt;/param-value&gt; - &lt;/init-param&gt; - &lt;init-param&gt; - &lt;param-name&gt;timeout&lt;/param-name&gt; - &lt;param-value&gt;120000&lt;/param-value&gt; - &lt;/init-param&gt; - &lt;init-param&gt; - &lt;param-name&gt;interval&lt;/param-name&gt; - &lt;param-value&gt;0&lt;/param-value&gt; - &lt;/init-param&gt; - &lt;init-param&gt; - &lt;param-name&gt;multiFrameInterval&lt;/param-name&gt; - &lt;param-value&gt;1500&lt;/param-value&gt; - &lt;/init-param&gt; - &lt;init-param&gt; - &lt;param-name&gt;logLevel&lt;/param-name&gt; - &lt;param-value&gt;0&lt;/param-value&gt; - &lt;/init-param&gt; - &lt;init-param&gt; - &lt;param-name&gt;JSONCommented&lt;/param-name&gt; - &lt;param-value&gt;false&lt;/param-value&gt; - &lt;/init-param&gt; - &lt;init-param&gt; - &lt;param-name&gt;alwaysResumePoll&lt;/param-name&gt; - &lt;param-value&gt;false&lt;/param-value&gt; &lt;!-- use true for x-site cometd --&gt; - &lt;/init-param&gt; - &lt;load-on-startup&gt;1&lt;/load-on-startup&gt; - &lt;/servlet&gt;</programlisting> - </section> - - <section> - <title>Environment</title> - - <para>Test running on our server for testing (Tornado)</para> - - <para>Processor : Intel(R) Xeon(R) CPU E5345 @ 2.33GHz (8 cores)</para> - - <para>RAM : 16 GB</para> - - <para>java version "1.5.0_15" (64-bit)</para> - </section> - - <section> - <title>Result</title> - - <table> - <title></title> - - <tgroup cols="4"> - <thead> - <row> - <entry align="center">Connection</entry> - - <entry align="center">Heap (JProfiler), mb</entry> - - <entry align="center">Virt (top),gb</entry> - - <entry align="center">res (top), gb</entry> - </row> - </thead> - - <tbody> - <row> - <entry>1000</entry> - - <entry>239</entry> - - <entry>-</entry> - - <entry>-</entry> - </row> - - <row> - <entry>2000</entry> - - <entry>318</entry> - - <entry>-</entry> - - <entry>-</entry> - </row> - - <row> - <entry>3000</entry> - - <entry>450</entry> - - <entry>6</entry> - - <entry>1.36</entry> - </row> - - <row> - <entry>4000</entry> - - <entry>610</entry> - - <entry>7.2</entry> - - <entry>1.6</entry> - </row> - - <row> - <entry>5000</entry> - - <entry>767</entry> - - <entry>12.9</entry> - - <entry>1.7</entry> - </row> - - <row> - <entry>6000</entry> - - <entry>895</entry> - - <entry>14.4</entry> - - <entry>1.8</entry> - </row> - - <row> - <entry>7000</entry> - - <entry>1004</entry> - - <entry>15.5</entry> - - <entry>2.2</entry> - </row> - - <row> - <entry>8000</entry> - - <entry>1116</entry> - - <entry>17.3</entry> - - <entry>2.6</entry> - </row> - - <row> - <entry>9000</entry> - - <entry>1295</entry> - - <entry>29.6</entry> - - <entry>9.8</entry> - </row> - </tbody> - </tgroup> - </table> - - <mediaobject> - <imageobject> - <imagedata fileref="images/cometd-bench.png" /> - </imageobject> - </mediaobject> - - <para>In screenshot red line show thousand of connection. Then count of - connection be 9000 the test fail, with exception connection - timeout.</para> - </section> -</chapter> Deleted: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/cometd-cluster.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/cometd-cluster.xml 2010-08-05 13:44:26 UTC (rev 2886) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/cometd-cluster.xml 2010-08-05 14:37:10 UTC (rev 2887) @@ -1,224 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="WS.Cometdcluster"> - <?dbhtml filename="ch-cometd-cluster.html"?> - - <title>Cometd cluster</title> - - <section> - <title>Motivation</title> - - <para>When we run Stress Testing Cometd (Jetty implementation) <ulink - url="http://docs.codehaus.org/display/JETTY/Stress+Testing+Cometd&qu... - we see that if we connect many clients, deliver message latency tends to - grow up. This situation described in article "20,000 Reasons Why Comet - Scales". <ulink - url="http://cometdaily.com/2008/01/07/20000-reasons-that-comet-scale... - So, in order to support a lot of concurrent cometd connections we need a - mean to horizontally scale eXo cometd support.</para> - - <mediaobject> - <imageobject> - <imagedata fileref="images/cometd-cluster.png" /> - </imageobject> - </mediaobject> - - <para>1- Getting base URL for cometd connection (one of the node in cometd - cluster)</para> - - <para>2 - Getting userToken at cometd server (it need for subscribing on - channel)</para> - - <para>3 - Sending message from Exo-server</para> - - <para>LoadBalancer - component that give base URL of one of free cometd - server.</para> - - <para>ContinuationServiceDelegate - component that send message from - Exo-server to client via cometd server there client is registered</para> - - <para>RESTContinuationService - component that receive message from - ContinuationServiceDelegate and delegate it to ContinuationServer and send - userToken generated by ContinuationServer for user.</para> - - <para>ContinuationService - component that provide cometd - connection.</para> - </section> - - <section> - <title>How it works</title> - - <para>To start work with cometd service the client should send request to - Exo-server with the username, receive with response URL one of cometd - servers (1 - on the scheme). This URL gives out LoadBalancer using the - information set in a configuration</para> - - <programlisting>&lt;init-params&gt; - &lt;object-param&gt; - &lt;name&gt;cometd.lb.configuration&lt;/name&gt; - &lt;description&gt;cometd lb nodes&lt;/description&gt; - &lt;object type="org.exoplatform.ws.frameworks.cometd.loadbalancer.LoadBalancerImpl$LoadBalancerConf"&gt; - &lt;field name="nodes"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;object type="org.exoplatform.ws.frameworks.cometd.loadbalancer.Node"&gt; - &lt;field name="id"&gt; - &lt;string&gt;1&lt;/string&gt; - &lt;/field&gt; - &lt;field name="url"&gt; - &lt;string&gt;http://localhost:8080&lt;/string&gt; - &lt;/field&gt; - &lt;field name="maxConnection"&gt; - &lt;int&gt;10&lt;/int&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;object type="org.exoplatform.ws.frameworks.cometd.loadbalancer.Node"&gt; - &lt;field name="id"&gt; - &lt;string&gt;2&lt;/string&gt; - &lt;/field&gt; - &lt;field name="url"&gt; - &lt;string&gt;http://localhost:8081&lt;/string&gt; - &lt;/field&gt; - &lt;field name="maxConnection"&gt; - &lt;int&gt;15&lt;/int&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; -&lt;/init-params&gt;</programlisting> - - <para>In the above configuration we described two cometd-cluseter nodes - of. Let's consider one of them.</para> - - <para>1 - are unique the identifier of node (id) http://localhost:8080 - - base URL 15 - the maximum number of the connected clients. LoadBalancer - chooses one of node in cometd cluster (on which connection is possible) - and associate with a name of the user! Now the client know on that cometd - server connection is possible, for this purpose it is necessary to request - userToken on cometd server(2). As for this need do request on other domain - client must use framework that allowed cross-domain-ajax. We have - framework that can do this task, how use this framework describe in - article - Framework for cross-domain AJAX. After client receive userToken - the client can do cometd-registration.</para> - - <para>Example: the Client with a name exo1 wishes to be connected to - cometd to service. It is necessary to make HTTP request (GET) on - Exo-server URL = "http://localhost:8080/rest/cometdurl/exo1" with the - answer receives a base URL of cometd server, it can be as a remote server - or local. We will assume that we use cluster and receive some thing like - this "http://192.168.0.21:8080". Further it is necessary get userToken - already from cometd server for this purpose do request (GET) URL - ="http://192.168.0.22:8081/rest/gettoken/exo1", after that we do standard - procedure for cometd connections.</para> - - <para>Then it is necessary to send the message to client - ContinuationServiceDelegate requests at LoadBalancer the cometd server - address on which the client is registered sends the message in format JSON - on cometd server should be RESTContinuationService which to accept the - message and to transfer them to ContinuationService (3)</para> - - <para>Example: we will want to send the message to the client exo1. For - this purpose ContinuationServiceDelegate requests to LoadBalancer the - information on that to what server the given user is connected, we will - receive necessary URL http://192.168.0.22:8081) and do HTTP request (POST) - on comets a server, URL = - "http://192.168.0.22:8080/rest/sendprivatemessage/" in a body the message - in format JSON is transferred, RESTContinuationService having received the - given message transfers it ContinuationService which already in turn - delivers it to the client.</para> - - <programlisting>&lt;configuration&gt; - &lt;component&gt; - &lt;type&gt;org.exoplatform.ws.frameworks.cometd.ContinuationService&lt;/type&gt; - &lt;/component&gt; - &lt;component&gt; - &lt;key&gt;org.mortbay.cometd.continuation.AbstractBayeux&lt;/key&gt; - &lt;type&gt;org.mortbay.cometd.continuation.EXoContinuationBayeux&lt;/type&gt; - &lt;/component&gt; - &lt;component&gt; - &lt;key&gt;org.exoplatform.ws.frameworks.cometd.transport.ContinuationServiceDelegate&lt;/key&gt; - &lt;type&gt;org.exoplatform.ws.frameworks.cometd.transport.ContinuationServiceRemoteDelegate&lt;/type&gt; - &lt;/component&gt; - &lt;component&gt; - &lt;type&gt;org.exoplatform.ws.frameworks.cometd.transport.RESTContinuationService&lt;/type&gt; - &lt;/component&gt; - &lt;component&gt; - &lt;type&gt;org.exoplatform.ws.frameworks.cometd.loadbalancer.RESTLoadBalancerService&lt;/type&gt; - &lt;/component&gt; - &lt;component&gt; - &lt;key&gt;org.exoplatform.ws.frameworks.cometd.loadbalancer.LoadBalancer&lt;/key&gt; - &lt;type&gt;org.exoplatform.ws.frameworks.cometd.loadbalancer.LoadBalancerImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;object-param&gt; - &lt;name&gt;cometd.lb.configuration&lt;/name&gt; - &lt;description&gt;cometd lb nodes&lt;/description&gt; - &lt;object type="org.exoplatform.ws.frameworks.cometd.loadbalancer.LoadBalancerImpl$LoadBalancerConf"&gt; - &lt;field name="nodes"&gt; - &lt;collection type="java.util.ArrayList"&gt; - &lt;value&gt; - &lt;object type="org.exoplatform.ws.frameworks.cometd.loadbalancer.Node"&gt; - &lt;field name="id"&gt; - &lt;string&gt;1&lt;/string&gt; - &lt;/field&gt; - &lt;field name="url"&gt; - &lt;string&gt;http://localhost:8080&lt;/string&gt; - &lt;/field&gt; - &lt;field name="maxConnection"&gt; - &lt;int&gt;10&lt;/int&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/value&gt; - &lt;value&gt; - &lt;object type="org.exoplatform.ws.frameworks.cometd.loadbalancer.Node"&gt; - &lt;field name="id"&gt; - &lt;string&gt;2&lt;/string&gt; - &lt;/field&gt; - &lt;field name="url"&gt; - &lt;string&gt;http://localhost:8081&lt;/string&gt; - &lt;/field&gt; - &lt;field name="maxConnection"&gt; - &lt;int&gt;15&lt;/int&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/value&gt; - &lt;/collection&gt; - &lt;/field&gt; - &lt;/object&gt; - &lt;/object-param&gt; -&lt;/init-params&gt; - &lt;/component&gt; -&lt;/configuration&gt;</programlisting> - - <para>The test: At testing running two servlet-containers Tomcat (in role - Exo - server'a) and Jetty (cometd server). A configuration example:</para> - - <programlisting>&lt;configuration clients="12" repeat="1" sleep-connection="500" sleep-sending="200"&gt; - &lt;container containerStart="false" port="8080" home=""/&gt; - &lt;messages&gt; - &lt;message broadcast="false" id="1"&gt;hello&lt;/message&gt; - &lt;message broadcast="true" id="2"&gt;hello!!!&lt;/message&gt; - &lt;/messages&gt; - &lt;cometd-url&gt;http://localhost:8080/cometd/cometd&lt;/cometd-url&gt; - &lt;base-url&gt;http://localhost:8080/rest/&lt;/base-url&gt; - &lt;channels&gt; - &lt;channel&gt;/eXo/comedt/test&lt;/channel&gt; - &lt;/channels&gt; -&lt;/configuration&gt;</programlisting> - - <para>configuration describe that we create 12 cometd connections with - sleep-connection = "500" (мс), will be subscribe on the channel - "/eXo/comedt/test". Then it will be sent two message "hello" "hello!!!" - the First individually to each of the clients, the second broadcast on the - channel. Messages delivered with an interval sleep-sending = "200". - <uri>http://localhost:8080/rest/</uri> - base URL of Exo - server. For - start test execute a command:</para> - - <programlisting>mvn clean install -f pom-test.xml -Dexo.test.skip=false -Djetty.home = "./target/jetty"</programlisting> - </section> -</chapter> Deleted: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/cometd.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/cometd.xml 2010-08-05 13:44:26 UTC (rev 2886) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/cometd.xml 2010-08-05 14:37:10 UTC (rev 2887) @@ -1,131 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="WS.Cometd"> - <?dbhtml filename="ch-cometd.html"?> - - <title>Cometd</title> - - <section> - <title>definition</title> - - <para>Comet is a World Wide Web application architecture in which a web - server sends data to a client program (normally a web browser) - asynchronously without any need for the client to explicitly request it. - It allows creation of event-driven web applications, enabling real-time - interaction which would otherwise require much more work. Though the term - Comet was coined in 2006, the idea is several years older, and has been - called various names, including server push, HTTP push, HTTP streaming, - Pushlets, Reverse Ajax, and others.</para> - - <para>Cometd on wikipedia <ulink - url="http://en.wikipedia.org/wiki/Comet_(programming)">http:... - - <para>It's an implementation of the Bayeux protocol.</para> - </section> - - <section> - <title>Use</title> - - <para>Cometd is deployed by default with the portal (only trunk version). - it's composed of a service and a webapp.</para> - - <para>To get access to the cometd, you need to get a key associated with - the login used in the portal.</para> - - <programlisting>public String getUserToken(String eXoId)</programlisting> - - <para>The connection has to be initialized, for doing so you can use the - cometd widget available by default in the portal.</para> - - <para>to send a message from the service to a user :</para> - - <programlisting>public void sendMessage(String eXoId, String channel, Object data)</programlisting> - </section> - - <section> - <title>Sample</title> - - <para>you can find a sample here <link - linkend="???">http://svn.exoplatform.org/svnroot/exoplatform... - - <para><command>To have it working :</command></para> - - <itemizedlist> - <listitem> - <para>deploy a trunk version of the portal</para> - </listitem> - - <listitem> - <para>go to ~/java/portal/trunk/sample/application/cometd/ and execute - exoproject --deploy=module</para> - </listitem> - - <listitem> - <para>start the portal</para> - </listitem> - - <listitem> - <para>load all the widgets and portlets</para> - </listitem> - - <listitem> - <para>in a page, add the cometd widget and the portlet - "CometdDemo"</para> - </listitem> - - <listitem> - <para>in the widget click on init</para> - </listitem> - - <listitem> - <para>in the CometdDemo portlet, type a message and click on "send", a - pop up with your message will appear on the top right and disappear - after 3 sec</para> - </listitem> - </itemizedlist> - - <para><command>What happened?</command></para> - - <itemizedlist> - <listitem> - <para>the portlet (JSR 286) sent an action with the message.</para> - </listitem> - - <listitem> - <para>the action called the continuation service and sent the message - to the user that had sent it</para> - </listitem> - - <listitem> - <para>the service sent the message to the browser</para> - </listitem> - - <listitem> - <para>the cometd client side received the message, and sent it to - topics</para> - </listitem> - - <listitem> - <para>in topic, the notification window listened to the topic - "/eXo/portal/notification" so the notification window appeared.</para> - </listitem> - </itemizedlist> - </section> - - <section> - <title>improvements</title> - - <itemizedlist> - <listitem> - <para>replace the token system by oAuth would probably be good. not - sure of how it is possible.</para> - </listitem> - - <listitem> - <para>There is no method yet to broadcast a message on a channel to - all the subscribers</para> - </listitem> - </itemizedlist> - </section> -</chapter> Deleted: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/introduction-to-rest.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/introduction-to-rest.xml 2010-08-05 13:44:26 UTC (rev 2886) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/introduction-to-rest.xml 2010-08-05 14:37:10 UTC (rev 2887) @@ -1,212 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id = "WS.Introduction"> - <?dbhtml filename="ch-introduction-to-rest.html"?> - - <title>Introduction to the Representational State Transfer (REST)</title> - - <section> - <title>Introduction</title> - - <para><command>Representational State Transfer (REST)</command> is a style - of software architecture for distributed hypermedia systems such as the - World Wide Web. The term was introduced in the doctoral dissertation in - 2000 by Roy Fielding, one of the principal authors of the Hypertext - Transfer Protocol (HTTP) specification, and has come into widespread use - in the networking community.</para> - - <para>REST strictly refers to a collection of network architecture - principles that outline how resources are defined and addressed. The term - is often used in a looser sense to describe any simple interface that - transmits domain-specific data over HTTP without an additional messaging - layer such as SOAP or session tracking via HTTP cookies.</para> - - <para>The key abstraction of information in REST is a - <command>resource</command>. Any information that can be named can be a - resource: a document or image, a temporal service (e.g. "today's weather - in Los Angeles"), a collection of other resources, a non-virtual object - (e.g. a person), and so on. In other words, any concept that might be the - target of an author's hypertext reference must fit within the definition - of a resource. A resource is a conceptual mapping to a set of entities, - not the entity that corresponds to the mapping at any particular point in - time.</para> - - <para>REST uses a <command>resource identifier </command>to identify the - particular resource involved in an interaction between components. REST - connectors provide a generic interface for accessing and manipulating the - value set of a resource, regardless of how the membership function is - defined or the type of software that is handling the request. URL or URN - are the examples of a resource identifier.</para> - - <para>REST components perform actions with a resource by using a - <command>representation</command> to capture the current or intended state - of that resource and transferring that representation between components. - A representation is a sequence of bytes, plus <command>representation - metadata </command>to describe those bytes. Other commonly used but less - precise names for a representation include: <command>document, file, and - HTTP message entity, instance, or variant</command>. A representation - consists of data, metadata describing the data, and, on occasion, metadata - to describe the metadata (usually for the purpose of verifying message - integrity). Metadata are in the form of name-value pairs, where the name - corresponds to a standard that defines the value's structure and - semantics. The data format of a representation is known as a media - type.</para> - - <table> - <title>REST Data Elements</title> - - <tgroup cols="2"> - <thead> - <row> - <entry align="center">Data Element</entry> - - <entry align="center">Modern Web Examples</entry> - </row> - </thead> - - <tbody> - <row> - <entry>resource</entry> - - <entry>the intended conceptual target of a hypertext - reference</entry> - </row> - - <row> - <entry>resource identifier</entry> - - <entry>URL, URN</entry> - </row> - - <row> - <entry>representation</entry> - - <entry>HTML document, JPEG image</entry> - </row> - - <row> - <entry>representation metadata</entry> - - <entry>media type, last-modified time</entry> - </row> - - <row> - <entry>resource metadata</entry> - - <entry>source link, alternates, vary</entry> - </row> - - <row> - <entry>control data</entry> - - <entry>if-modified-since, cache-control</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>REST uses various <command>connector</command> types to encapsulate - the activities of accessing resources and transferring resource - representations. The connectors present an abstract interface for - component communication, enhancing simplicity by providing a complete - separation of concepts and hiding the underlying implementation of - resources and communication mechanisms.</para> - - <table> - <title>REST Connectors</title> - - <tgroup cols="2"> - <thead> - <row> - <entry align="center">Connector</entry> - - <entry align="center">Modern Web Examples</entry> - </row> - </thead> - - <tbody> - <row> - <entry>client</entry> - - <entry>libwww, libwww-perl</entry> - </row> - - <row> - <entry>server</entry> - - <entry>libwww, Apache API, NSAPI</entry> - </row> - - <row> - <entry>cache</entry> - - <entry>browser cache, Akamai cache network</entry> - </row> - - <row> - <entry>resolver</entry> - - <entry>bind (DNS lookup library)</entry> - </row> - - <row> - <entry>tunnel</entry> - - <entry><para></para>SOCKS, SSL after HTTP CONNECT</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>The primary connector types are client and server. The essential - difference between the two is that a client initiates communication by - making a request, whereas a server listens for connections and responds to - requests in order to supply access to its services. A component may - include both client and server connectors.</para> - - <para>An important part of RESTful architecture is a well-defined - interface to communicate, in particular it is a set of HTTP methods such - as POST, GET, PUT and DELETE. These methods are often compared with the - CREATE, READ, UPDATE, DELETE (CRUD) operations associated with database - technologies. An analogy can also be made:</para> - - <itemizedlist> - <listitem> - <para>PUT is analogous to CREATE or PASTE OVER,</para> - </listitem> - - <listitem> - <para>GET to READ or COPY,</para> - </listitem> - - <listitem> - <para>POST to UPDATE or PASTE AFTER, and</para> - </listitem> - - <listitem> - <para>DELETE to DELETE or CUT.</para> - </listitem> - </itemizedlist> - - <para><command>Note</command>: RESTful architecture is not limited to - those methods, one of good examples of extension is the WebDAV - protocol.</para> - - <para>The <command>CRUD</command> (Create, Read, Update and Delete) verbs - are designed to operate with atomic data within the context of a database - transaction. REST is designed around the atomic transfer of a more complex - state and can be viewed as a mechanism for transferring structured - information from one application to another.</para> - - <para>HTTP separates the notions of a web server and a web browser. This - allows the implementation of each to vary from the other based on the - client/server principle. When used RESTfully, HTTP is - <command>stateless</command>. Each message contains all the information - necessary to understand the request.</para> - - <para>As a result, neither the client nor the server needs to remember any - communication-state between messages. Any state retained by the server - must be modeled as a resource..</para> - </section> -</chapter> Deleted: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/javascript-webdav-library.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/javascript-webdav-library.xml 2010-08-05 13:44:26 UTC (rev 2886) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/javascript-webdav-library.xml 2010-08-05 14:37:10 UTC (rev 2887) @@ -1,355 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="WS.JavaScriptWebDAVLibrary"> - <?dbhtml filename="ch-javascript-webdav-library.html"?> - - <title>JavaScript WebDAV Library</title> - - <section> - <title>Introduction to the JavaScript WebDAV library</title> - - <para>I am proud to introduce JavaScript WebDAV library webdav.js which - based on AJAX. This library consists the special class webdav which is - aimed to make all requests supported by eXo Platform WebDAV-server with - supported parameters.</para> - - <para>Proposed library supports asynchronous (on default) and synchronous - mode of AJAX request processing. To set one of some of this mode you - should call webdav.setAsynchronous() or webdav.setSynchronous() - method.</para> - - <para>Also this library can fulfill BASIC HTTP authentication using value - of preset webdav.username and webdav.password properties.</para> - - <para>Scheme of WebDAV data exchange:</para> - - <mediaobject> - <imageobject> - <imagedata fileref="images/javascript-webdav.png" /> - </imageobject> - </mediaobject> - </section> - - <section> - <title>Content of JavaScript WebDAV Library:</title> - - <para>There is a list of realized methods:</para> - - <itemizedlist> - <listitem> - <para>ExtensionMethod(handler, path, options) method - a simple - constructor of the user-defined WebDAV request.</para> - </listitem> - </itemizedlist> - - <para>1. WebDAV Modifications to HTTP Operations:</para> - - <itemizedlist> - <listitem> - <para>GET(handler, path, options) method - retrieves the content of a - resource.</para> - </listitem> - - <listitem> - <para>PUT(handler, path, options) method - saves the content of a - resource to the server.</para> - </listitem> - - <listitem> - <para>DELETE(handler, path, options) method - removes a resource or - collection.</para> - </listitem> - - <listitem> - <para>OPTIONS(handler, path, options) method - returns the HTTP - methods that the server supports for specified URL.</para> - </listitem> - - <listitem> - <para>MKCOL(handler, path, options) method - creates a - collection.</para> - </listitem> - - <listitem> - <para>COPY(handler, path, options) method - copies a resource from one - URI to another.</para> - </listitem> - - <listitem> - <para>MOVE(handler, path, options) method - moves a resource from one - URI to another.</para> - </listitem> - - <listitem> - <para>HEAD(handler, path, options) method - asks for the response - identical to the one that would correspond to a HEAD request, but - without the response body. This is useful for retrieving - meta-information written in response headers, without having to - transport the entire content.</para> - </listitem> - </itemizedlist> - - <para>2. WebDAV Property Operations:</para> - - <itemizedlist> - <listitem> - <para>PROPFIND(handler, path, options) method - retrieves properties, - stored as XML, from a resource. It is also overloaded to allow one to - retrieve the collection structure (a.k.a. directory hierarchy) of a - remote system.</para> - </listitem> - - <listitem> - <para>PROPPATCH(handler, path, options) method - changes and deletes - multiple properties on a resource in a single atomic act.</para> - </listitem> - </itemizedlist> - - <para>3. WebDAV Lock Operations:</para> - - <itemizedlist> - <listitem> - <para>LOCK(handler, path, options) method - puts a lock on a - resource.</para> - </listitem> - - <listitem> - <para>UNLOCK(handler, path, options) method - removes a lock from a - resource.</para> - </listitem> - </itemizedlist> - - <para>4. WebDAV Versioning Extension Operations:</para> - - <itemizedlist> - <listitem> - <para>VERSIONCONTROL(handler, path, options) method - is used to - create a new version-controlled resource for an existing version - history. This allows the creation of version-controlled resources for - the same version history in multiple workspaces.</para> - </listitem> - - <listitem> - <para>CHECKOUT(handler, path, options) method - can be applied to a - checked-in version-controlled resource to allow modifications to the - content and dead properties of that version-controlled - resource.</para> - </listitem> - - <listitem> - <para>CHECKIN(handler, path, options) method - can be applied to a - checked-out version-controlled resource to produce a new version whose - content and dead properties are copied from the checked-out - resource.</para> - </listitem> - - <listitem> - <para>UNCHECKOUT(handler, path, options) method - can be applied to a - checked-out version-controlled resource to cancel the CHECKOUT and - restore the pre-CHECKOUT state of the version-controlled - resource.</para> - </listitem> - - <listitem> - <para>REPORT(handler, path, options) method - an extensible mechanism - for obtaining information about a resource.</para> - </listitem> - - <listitem> - <para>ORDERPATCH(handler, path, options) method - is used to change - the ordering semantics of a collection, to change the order of the - collection's members in the ordering, or both.</para> - </listitem> - </itemizedlist> - - <para>5. WebDAV SEARCH Operation:</para> - - <itemizedlist> - <listitem> - <para>SEARCH(handler, path, options) method - a lightweight search - method to transport queries and result sets that allows clients to - make use of server-side search facilities retrieve properties, stored - as XML, from a resource.</para> - </listitem> - </itemizedlist> - - <para>If there is no interested WebDAV method in the list above, you can - use ExtensionMethod(handler, path, options) to construct WebDAV request - you like with your own:</para> - - <itemizedlist> - <listitem> - <para>name of method (passing throw parameter options.method)</para> - </listitem> - - <listitem> - <para>request headers (passing throw parameter options.headers) - and</para> - </listitem> - - <listitem> - <para>request body (passing throw parameter options.body).</para> - </listitem> - </itemizedlist> - - <para>First parameter of each method - hanlder - is an object {onSuccess , - onError, onComplete}, which describes three functions to call when the - request either succeeds or fails, and completes:</para> - - <itemizedlist> - <listitem> - <para>handler.onSuccess - will call if the request succeeds,</para> - </listitem> - - <listitem> - <para>handler.onError - will call if the request fails,</para> - </listitem> - - <listitem> - <para>handler.onComplete - will call if the request completes.</para> - </listitem> - </itemizedlist> - - <para>Additionally you can add your own headers to the request by using - the special parameter options.</para> - - <para>Each method returns object result which consists next - properties:</para> - - <itemizedlist> - <listitem> - <para>result.status - status of XMLHttp response,</para> - </listitem> - - <listitem> - <para>result.statusstring - an explanation of status,</para> - </listitem> - - <listitem> - <para>result.headers - object with hash of XMLHttpRequest - response.getAllResponseHeaders() (e.g. if this the response header is - "Content-Type: test/plain" then result.headers['Content-Type'] = - 'test/plain'),</para> - </listitem> - - <listitem> - <para>result.content = XMLHttprequest response.responseXML if - response.header['Content-Type'] consists 'xml', or = XMLHttpRequest - response.responseText otherwise.</para> - </listitem> - </itemizedlist> - </section> - - <section> - <title>Example of using of JavaScript WebDAV library</title> - - <para>An example of using WebDAV library for the eXo Platform - WebDAV-server:</para> - - <programlisting>&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"&gt; -&lt;html&gt; -&lt;head&gt; - &lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /&gt; - &lt;title&gt;Demonstration of the eXo Platform Client Library of WebDAV&lt;/title&gt; - &lt;script type="text/javascript" src="js/webdav.js"&gt;&lt;/script&gt; - &lt;script&gt; - -// Example of using of eXo Platform Client Library of WebDAV -/** - * Serialize an XML Document or Element and return it as a string. - */ -function XMLtoString(node) { - if (typeof node != 'object') return node; - if (typeof XMLSerializer != "undefined") - return (new XMLSerializer( )).serializeToString(node); - else if (node.xml) return node.xml; - else throw "XML.serialize is not supported or can't serialize " + node; -}; - -// get and setup webdav object - var webdav = new Webdav('localhost', '8080'); - - webdav.username = 'root'; - webdav.password = 'exo'; - -// define webdav methods handlers - function handler_onSuccess(result) { - alert('Request SUCCEEDED with status = ' + result.status + ': ' + result.statusstring); - }; - - function handler_onError(result) { - alert('Request FAILED with status = ' + result.status + ': ' + result.statusstring); - }; - -var handler = { - onSuccess: handler_onSuccess, - onError: handler_onError, - onComplete: MKCOL_handler_onComplete -} - -// for eXoPlatform webdav -var default_webdav_path = '/rest/jcr/repository/collaboration'; - -// create a collection 'test' -webdav.MKCOL(handler, default_webdav_path + '/test1'); - -// create a resource 'example.txt' with content 'an example' - function MKCOL_handler_onComplete(result) { - // create a resource 'example.txt' with content 'an example' - var options = { -content: 'an example', -content_type: 'text/plain; charset=UTF-8' - } - handler.onComplete = PUT_handler_onComplete; - webdav.PUT(handler, default_webdav_path + '/test1/example.txt', options); - }; - -// put resource example.txt under version control - function PUT_handler_onComplete(result) { - // put resource example.txt under version control - handler.onComplete = VERSIONCONROL_handler_onComplete; - webdav.VERSIONCONTROL(handler, default_webdav_path + '/test1/example.txt'); - }; - -// obtain the 'version-tree' WebDAV report about 'example.txt' - function VERSIONCONROL_handler_onComplete(result) { - // obtain the 'version-tree' WebDAV report about 'example.txt' - var options = { - depth: '0', - type: 'version-tree' - }; - handler.onComplete = REPORT_handler_onComplete; - webdav.REPORT(handler, default_webdav_path + '/test1/example.txt', options); - }; - - // delete the collection 'test' - function REPORT_handler_onComplete(result) { - if ( result.content ) -alert( 'Response of server: ' + XMLtoString(result.content) ); - - // delete the collection 'test' - handler.onComplete = 'function() {}'; - webdav.DELETE(handler, default_webdav_path + '/test1/'); - }; - &lt;/script&gt; -&lt;/head&gt; -&lt;body&gt; - &lt;h2&gt;Demonstration of the eXo Platform Client Library of WebDAV&lt;/h2&gt; -&lt;/body&gt; -&lt;/html&gt;</programlisting> - </section> - - <section> - <title>How to get JavaScript WebDAV library</title> - - <para>You can get this library at the <ulink - url="http://svn.exoplatform.org/svnroot/exoplatform/projects/ws/bran... - - <para>Demonstration page was placed as <ulink - url="http://svn.exoplatform.org/svnroot/exoplatform/projects/ws/bran... - - <para>JSDoc is available at the <ulink - url="http://svn.exoplatform.org/svnroot/exoplatform/projects/ws/bran... - </section> -</chapter> Deleted: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/kerberos-sso-on-active-directory.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/kerberos-sso-on-active-directory.xml 2010-08-05 13:44:26 UTC (rev 2886) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/kerberos-sso-on-active-directory.xml 2010-08-05 14:37:10 UTC (rev 2887) @@ -1,304 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="WS.KerberosSSOOnActiveDirectory"> - <?dbhtml filename="ch-kerberos-sso-on-active-directory.html"?> - - <title>Kerberos SSO on Active Directory</title> - - <section> - <title>Overview</title> - - <para>ExoPortal allows to use SSO (Single Sign On) with Kerberos - authentication on a Microsoft Active Directory. To install this - functionality, some configuration is needed, on the Active Directory - server and on the application server.</para> - - <para>In this example, we suppose that the complete name of the machine on - which Tomcat server runs is ubu.exoua-int, and that it runs on the Linux - host (Ubuntu 7.04). This machine must be in Windows domain. How to do it - read in Samba documentation.</para> - - <para>Our implementation makes it possible to use SPNEGO or NTLM - (sometimes this two terms can be mixed, but here we will try to separate - it). The client will get two authentication headers 'Negotiate' and 'NTLM' - and will use supported by client (browser). In Firefox it is possible to - manage authentication types, in IE this is not possible. This HOWTO will - describe how to make configuration to support both authentication types. - In fact for IE SPNEGO will work.</para> - </section> - - <section> - <title>Active Directory configuration</title> - - <para>On the AD server, we need to create a Kerberos identification for - Tomcat Server :</para> - - <para>1. Create a user account for the host computer on which Tomcat - Server runs in the Active Directory server. (Select New &gt; User, not New - &gt; Machine.)</para> - - <para>When creating the two user accounts, use the simple name of the - computer, and I recommend give names as next pattern host_host-name and - http_host-name. First account will be used for LDAP connection, second one - will be used for authentication service via HTTP. For example, if the host - name is ubu.exoua-int, create a users in Active Directory called host_ubu - and http_ubu.</para> - - <para>Note the password you defined when creating the user account. You - will need it in step 3. Do not select the "User must change password at - next login" option, or any other password options.</para> - - <para>2. Configure the new user account to comply with the Kerberos - protocol.</para> - - <itemizedlist> - <listitem> - <para>Right-click the name of the user account in the Users tree in - the left pane and select Properties.</para> - </listitem> - </itemizedlist> - - <itemizedlist> - <listitem> - <para>NOTE Make sure the box "Use DES encryption types for this - account" is unchecked. Also make sure no other boxes are checked, - particularly the box "Do not require Kerberos - pre-authentication."</para> - </listitem> - - <listitem> - <para>Setting the encryption type may corrupt the password. Therefore, - you should reset the user password by right-clicking the name of the - user account, selecting Reset Password, and re-entering the same - password specified earlier.</para> - </listitem> - </itemizedlist> - - <para>3. Generate keys for service.</para> - - <programlisting>C:\&gt; ktpass -princ host/ubu.exoua-int@EXOUA-INT -mapuser host_ubu@EXOUA-INT -crypto RC4-HMAC-NT \ --ptype KRB5_NT_PRINCIPAL -mapop set -pass 123456 -out c:\host_ubu.keytab - - -C:\&gt; ktpass -princ HTTP/ubu.exoua-int@EXOUA-INT -mapuser http_ubu@EXOUA-INT -crypto RC4-HMAC-NT \ --ptype KRB5_NT_PRINCIPAL -mapop set -pass 123456 -out c:\http_ubu.keytab</programlisting> - - <para>4. Use the setspn utility to create the Service Principal Names - (SPNs) for the user account created in step 1. Enter the following - commands:</para> - - <programlisting>C:\&gt; setspn -A host/ubu.exoua-int host_ubu -C:\&gt; setspn -A HTTP/ubu.exoua-int http_ubu</programlisting> - - <para>5. Check which SPNs are associated with your user account, using the - following command:</para> - - <programlisting>C:\&gt; setspn -L host_ubu</programlisting> - - <para>NOTE This is an important step. If the same service is linked to a - different account in the Active Directory server, the client will not send - a Kerberos ticket to the server. If filter will be used secure-constraint - must be removed from web.xml</para> - - <para>6. Configuration on Linux host. This is example of file - /etc/krb5.conf</para> - - <programlisting>[logging] - default = FILE:/var/log/krb5libs.log - kdc = FILE:/var/log/krb5kdc.log - admin_server = FILE:/var/log/kadmind.log - -[libdefaults] - ticket_lifetime = 24000 - default_realm = EXOUA-INT - default_tkt_enctypes = rc4-hmac - default_tgs_enctypes = rc4-hmac - -[realms] - EXOUA-INT = { - kdc = test01-srv.exoua-int:88 - admin_server = test01-srv.exoua-int:749 - default_domain = EXOUA-INT - } - -[domain_real] - .exoua-int = EXOUA-INT - exoua-int = EXOUA-INT - -[kdc] - profile = /etc/kdc.conf - -[pam] - debug = false - ticket_lifetime = 36000 - renew_lifetime = 36000 - forwardable = true - krb4_convert = false</programlisting> - - <para>7. Copy key generated on step 3 to the Linux machine where tomcat - server runs.</para> - - <para>8. Run the ktutil utility on the Linux machine and import - keys.</para> - - <programlisting>andrew@ubu:~$ ktutil -ktutil: rkt host_ubu.keytab -ktutil: wkt host.keytab -ktutil: rkt http_ubu.keytab -ktutil: wkt http.keytab</programlisting> - - <para>You must get to new files with tickets.</para> - </section> - - <section> - <title>Setup webserver</title> - - <para>1. Deploy an exo-tomcat, and copy the jar for SSO in lib folder and - change configuration.xml file to your network settings :</para> - - <programlisting>&lt;configuration&gt; - &lt;component&gt; - &lt;key&gt;org.exoplatform.services.security.sso.config.SSOConfigurator&lt;/key&gt; - &lt;type&gt;org.exoplatform.services.security.sso.config.SSOConfigurator&lt;/type&gt; - &lt;init-params&gt; - &lt;properties-param&gt; - &lt;name&gt;sso-properties&lt;/name&gt; - &lt;property name="charset" value="UnicodeLittleUnmarked" /&gt; - &lt;property name="domain" value="EXOUA-INT" /&gt; - &lt;property name="jaas-context" value="krb5.ldap-action" /&gt; - &lt;property name="ldap-server" value="ldap://test01-srv.exoua-int:389/" /&gt; - &lt;!-- - ********************************************************** - Default cross domain authentication is disabled. - NOTE: This is actual for NTLM only. - For SPNEGO cross domain authentication is disabled by default. - There is some more work to enable it for SPNEGO. - ********************************************************** - --&gt; - &lt;!-- - &lt;property name="cross-domain" value="true" /&gt; - --&gt; - &lt;!-- - &lt;property name="redirect-on-error" value="http://google.com" /&gt; - --&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; - &lt;/component&gt;</programlisting> - - <para>2. In exo-tomcat/conf/Catalina/localhost/, change a file portal.xml - :</para> - - <programlisting>&lt;Context path='/portal' docBase='portal' debug='0' reloadable='true' crossContext='true'&gt; - &lt;Logger className='org.apache.catalina.logger.SystemOutLogger' - prefix='localhost_portal_log.' suffix='.txt' timestamp='true'/&gt; - &lt;Manager className='org.apache.catalina.session.PersistentManager' saveOnRestart='false'/&gt; - &lt;!-- - &lt;Realm className='org.apache.catalina.realm.JAASRealm' - appName='exo-domain' - userClassNames='org.exoplatform.services.security.jaas.UserPrincipal' - roleClassNames='org.exoplatform.services.security.jaas.RolePrincipal' - debug='0' cache='false'/&gt; - &lt;Valve className='org.apache.catalina.authenticator.FormAuthenticator' characterEncoding='UTF-8'/&gt; - --&gt; - &lt;Valve className="org.exoplatform.services.security.sso.tomcat.SSOAuthenticatorValve"/&gt; -&lt;/Context&gt;</programlisting> - - <para>Secure configuration in web.xml must be changed to next:</para> - - <programlisting>&lt;security-role&gt; - &lt;description&gt;a simple user role&lt;/description&gt; - &lt;role-name&gt;users&lt;/role-name&gt; - &lt;/security-role&gt; - - &lt;security-constraint&gt; - &lt;web-resource-collection&gt; - &lt;web-resource-name&gt;portal&lt;/web-resource-name&gt; - &lt;url-pattern&gt;/*&lt;/url-pattern&gt; - &lt;/web-resource-collection&gt; - &lt;auth-constraint&gt; - &lt;role-name&gt;users&lt;/role-name&gt; - &lt;/auth-constraint&gt; - - &lt;user-data-constraint&gt; - &lt;transport-guarantee&gt;NONE&lt;/transport-guarantee&gt; - &lt;/user-data-constraint&gt; - &lt;/security-constraint&gt;</programlisting> - - <para>NOTE At list one roles in web.xml must be corresponding to user - group in AD.</para> - - <para>3. Download in lib folder jcif-1.2.17.jar . We need this for support - NTLM authentication.</para> - - <para>4. In exo-tomcat/conf/jaas.conf, add :</para> - - <programlisting>com.sun.security.jgss.accept { - com.sun.security.auth.module.Krb5LoginModule required - keyTab = "/home/andrew/http.keytab" - useKeyTab = true - storeKey = true - principal = "HTTP/ubu.exoua-int@EXOUA-INT" - doNotPrompt = true - realm = "EXOUA-INT" - refreshKrb5Config = true - debug = false - ; -}; - -krb5.ldap-action { - com.sun.security.auth.module.Krb5LoginModule required - keyTab = "/home/andrew/host.keytab" - useKeyTab = true - storeKey = true - principal = "host/ubu.exoua-int@EXOUA-INT" - doNotPrompt = true - realm = "EXOUA-INT" - refreshKrb5Config = true - debug = false - ; -};</programlisting> - - <para>5. Add next system properties in file bin/eXo.sh</para> - - <programlisting>KERBEROS="-Djavax.security.auth.useSubjectCredsOnly=false \ --Djava.security.krb5.kdc=test01-srv.exoua-int \ --Djava.security.krb5.realm=EXOUA-INT" - -JAVA_OPTS="$YOURKIT_PROFILE_OPTION $JAVA_OPTS $LOG_OPTS $SECURITY_OPTS $EXO_OPTS $EXO_CONFIG_OPTS $KERBEROS"</programlisting> - - <para>6. For portal add one more filter for initialize Identity for user - org.exoplatform.services.security.sso.http.JndiIdentityInitalizerFilter - this filter must be mapped before - org.exoplatform.services.security.web.SetCurrentIdentityFilter on private - area.</para> - - <para>7. For Firefox, there is an additionnal configuration to do to use - AD authentication : in adress bar, go to about:config. Filter on ntlm and - choose "network.automatic-ntlm-auth.trusted-uris". Set string to the name - of the machine where webserver run (in this exemple : set "ubu"). For IE, - there is no additional configuration.</para> - - <para>8. Go to <uri>http://ubu.exoua-int:8080/portal/private/classic</uri> - If use was login windows (domain authentication) then, Active directory - authentication will be used.</para> - - <para>Instead tomcat valve - org.exoplatform.services.security.sso.tomcat.SSOAuthenticatorValve can be - used filter - org.exoplatform.services.security.sso.http.SSOAuthenticationFilter</para> - - <para>9. Important about using NTLM. JCIF may use MAC for signature - connection to DC. In this case when one user logined, then next user may - be not able login during time specified in property - jcifs.smb.client.soTimeout (in ms), default 15000. This time JCIF keeps - previous connection opened and may not create new one to authenticate - other user. Must be set next properties to fix this - jcifs.smb.client.domain, jcifs.smb.client.username, - jcifs.smb.client.password. For example</para> - - <programlisting>-Djcifs.smb.client.domain=EXOUA-INT -Djcifs.smb.client.username=Admin -Djcifs.smb.client.password=secret"</programlisting> - - <para>In this case SMB connection will be signed for user.</para> - </section> -</chapter> Deleted: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/oauth.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/oauth.xml 2010-08-05 13:44:26 UTC (rev 2886) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/oauth.xml 2010-08-05 14:37:10 UTC (rev 2887) @@ -1,285 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="WS.oAuth"> - <?dbhtml filename="ch-oauth.html"?> - - <title>oAuth</title> - - <section> - <title>Overview</title> - - <para>OAuth allows to grant access to private resources on one site (which - is called the Service Provider), to another site (called Consumer). OAuth - is giving access to a resource without sharing your identity at all. More - about oAuth at the site <ulink - url="http://oauth.net/">http://oauth.net/</ulink>;. (OAuth protocol: <ulink - url="http://oauth.net/core/1.0/">http://oauth.net/core/1.0/&... - - <para>This article describes how to configure our implementation of oAuth - service and client part. Both parts, service (Provider) and client - (Consumer) are based on oAuth core, this code can be found here <ulink - url="http://oauth.googlecode.com/svn/code/java/core/">http:/... - - <para>Our implementation can be found here <ulink - url="http://svn.exoplatform.org/svnroot/exoplatform/projects/ws/trun... - </section> - - <section> - <title>Provider</title> - - <para>The provider consists of two parts oauthprovider.war and - exo.ws.security.oauth.provider.service-trunk.jar. The main part of the - provider is OAuthProviderService, currently there is one implementation of - this interface - org.exoplatform.ws.security.oauth.impl.OAuthProviderServiceMD5Impl; this - component has few required configuration parameters.</para> - - <section> - <title>Configuration</title> - - <para>The configuration is defined in the file configuration.xml.</para> - - <programlisting>&lt;component&gt; - &lt;type&gt;org.exoplatform.ws.security.oauth.impl.OAuthProviderServiceMD5Impl&lt;/type&gt; - &lt;init-params&gt; - &lt;properties-param&gt; - &lt;name&gt;exo1&lt;/name&gt; - &lt;property name="secret" value="81d1b5d080d1" /&gt; - &lt;property name="description" value="description" /&gt; - &lt;property name="callbackURL" value="http://localhost:8080/ws-examples/callback" /&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; -&lt;/component&gt;</programlisting> - - <para>Properties:</para> - - <para>1. <command>name</command>: the name of provider, the client will - send the name of provider that it wants to use.</para> - - <para>2. <command>secret</command>: this property is used for subscribe - requests, this property must be known to the provider and the - consumer.</para> - - <para>3. <command>description</command>: any description of the - provider. Optional.</para> - - <para>4. <command>callbackURL</command>: this is URL where the client - will be redirected after successful authentication by the - provider.</para> - - <para>That is all what is needed for the configuration of the provider - service. The next part of configuration is about web, such as - servlets.</para> - </section> - - <section> - <title>Servlets</title> - - <para>The web part of the provider consists of 3 servlets:</para> - - <itemizedlist> - <listitem> - <para>OAuthRequestTokenServlet,</para> - </listitem> - - <listitem> - <para>OAuthAccessTokenServlet, and</para> - </listitem> - - <listitem> - <para>OAuthAuthorizationServlet</para> - </listitem> - </itemizedlist> - - <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; -&lt;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"&gt; - &lt;display-name&gt;oAuth provider&lt;/display-name&gt; - &lt;context-param&gt; - &lt;description&gt;Login page name&lt;/description&gt; - &lt;param-name&gt;login-page&lt;/param-name&gt; - &lt;param-value&gt;login/jsp/login.jsp&lt;/param-value&gt; - &lt;/context-param&gt; - &lt;servlet&gt; - &lt;servlet-name&gt;OAuthAuthenticationServlet&lt;/servlet-name&gt; - &lt;servlet-class&gt;org.exoplatform.ws.security.oauth.http.OAuthAuthenticationServlet&lt;/servlet-class&gt; - &lt;/servlet&gt; - &lt;servlet&gt; - &lt;servlet-name&gt;OAuthRequestTokenServlet&lt;/servlet-name&gt; - &lt;servlet-class&gt;org.exoplatform.ws.security.oauth.http.OAuthRequestTokenServlet&lt;/servlet-class&gt; - &lt;/servlet&gt; - &lt;servlet&gt; - &lt;servlet-name&gt;OAuthAccessTokenServlet&lt;/servlet-name&gt; - &lt;servlet-class&gt;org.exoplatform.ws.security.oauth.http.OAuthAccessTokenServlet&lt;/servlet-class&gt; - &lt;/servlet&gt; - &lt;servlet-mapping&gt; - &lt;servlet-name&gt;OAuthAuthenticationServlet&lt;/servlet-name&gt; - &lt;url-pattern&gt;/authorize/*&lt;/url-pattern&gt; - &lt;/servlet-mapping&gt; - &lt;servlet-mapping&gt; - &lt;servlet-name&gt;OAuthRequestTokenServlet&lt;/servlet-name&gt; - &lt;url-pattern&gt;/request_token/*&lt;/url-pattern&gt; - &lt;/servlet-mapping&gt; - &lt;servlet-mapping&gt; - &lt;servlet-name&gt;OAuthAccessTokenServlet&lt;/servlet-name&gt; - &lt;url-pattern&gt;/access_token/*&lt;/url-pattern&gt; - &lt;/servlet-mapping&gt; -&lt;/web-app&gt;</programlisting> - </section> - </section> - - <section> - <title>Consumer</title> - - <para>The consumer consists of OAuthConsumerService and web part (servlets - and filters).</para> - - <section> - <title>How it works</title> - - <para>OAuthConsumerFilter checks cookies in client's request. The cookie - must have the name _consumer_name_.oauth_token and - _consumer_name_.oauth_token_secret. Then this filter try to find the - request/access token this at OAuthConsumerService. If the token from the - request is an access token then the client is already authenticated and - gets access to requested resource.</para> - - <para>Otherwise the client will be redirected to the provider for - authentication (see below, property "provider.authorizationURL"). This - is the part of configuration.xml for the consumer:</para> - - <programlisting>&lt;component&gt; - &lt;type&gt;org.exoplatform.ws.security.oauth.impl.OAuthConsumerServiceImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;!-- this parameter MUST be set in minutes --&gt; - &lt;name&gt;tokenAliveTime&lt;/name&gt; - &lt;value&gt;300&lt;/value&gt; - &lt;/value-param&gt; - &lt;properties-param&gt; - &lt;name&gt;exo1&lt;/name&gt; - &lt;property name="secret" value="81d1b5d080d1" /&gt; - &lt;property name="description" value="description" /&gt; - &lt;property name="provider.tokenRequestURL" value="http://localhost:8080/oauthprovider/request_token" /&gt; - &lt;property name="provider.authorizationURL" value="http://localhost:8080/oauthprovider/authorize" /&gt; - &lt;property name="provider.accessTokenURL" value="http://localhost:8080/oauthprovider/access_token" /&gt; - &lt;/properties-param&gt; - &lt;/init-params&gt; -&lt;/component&gt; -&lt;component&gt; - &lt;type&gt;org.exoplatform.ws.security.oauth.impl.OAuthClientHttpImpl&lt;/type&gt; -&lt;/component&gt; -&lt;component&gt; - &lt;type&gt;org.exoplatform.ws.security.oauth.impl.OAuthTokenCleanerImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;!-- this parameter MUST be set in minutes --&gt; - &lt;name&gt;tokenCleanerTimeout&lt;/name&gt; - &lt;value&gt;3&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; -&lt;/component&gt;</programlisting> - - <para>The client is redirected for authentication to the provider with - the required parameters (request and secret token), before this token - OAuthClient got from the provider (see configuration, property - "provider.tokenRequestURL"). On the provider side, the user (if the - authentication is successful and has valid request parameters) will be - redirected to the consumer again (see property "callbackURL" in the - provider configuration). Then the consumer (this is, the same as - receiving request token, invisible for the client) receives the access - token, and redirects the client to the original URL. Then the filter - checks the token from the request and gives access to the requested - resource.</para> - </section> - - <section> - <title>web.xml</title> - - <para>This is the file web.xml for consumer application, in this example - the resource http://localhost:8080/ws-examples/oauth/protected/ is under - oAuth protect :</para> - - <programlisting>&lt;filter&gt; -&lt;filter-name&gt;OAuthConsumerFilter&lt;/filter-name&gt; - &lt;filter-class&gt;org.exoplatform.ws.security.oauth.http.OAuthConsumerFilter&lt;/filter-class&gt; - &lt;init-param&gt; - &lt;param-name&gt;consumer&lt;/param-name&gt; - &lt;param-value&gt;exo1&lt;/param-value&gt; -&lt;/init-param&gt; &lt;/filter&gt; &lt;filter&gt; -&lt;filter-name&gt;OAuthRequestWrapperFilter&lt;/filter-name&gt; -&lt;filter-class&gt;org.exoplatform.ws.security.oauth.http.OAuthRequestWrapperFilter&lt;/filter-class&gt; &lt;/filter&gt; - &lt;filter-mapping&gt; -&lt;filter-name&gt;OAuthConsumerFilter&lt;/filter-name&gt; -&lt;url-pattern&gt;/oauth/protected/*&lt;/url-pattern&gt; -&lt;/filter-mapping&gt; -&lt;filter-mapping&gt; -&lt;filter-name&gt;OAuthRequestWrapperFilter&lt;/filter-name&gt; -&lt;url-pattern&gt;/oauth/protected/*&lt;/url-pattern&gt; -&lt;/filter-mapping&gt;</programlisting> - - <para>Any resource can be protected by this mechanism under the - condition that web.xml is configured to use OAuthConsumerFilter. Client - must save the given access and the secret token in a cookie.</para> - </section> - - <section> - <title>Stages</title> - - <mediaobject> - <imageobject> - <imagedata fileref="images/oauth-scheme.png" /> - </imageobject> - </mediaobject> - - <para>1. continuous line - client's redirections</para> - - <para>2. fine dashed line - internal oAuth schema requests and - responses.</para> - - <para>Stages:</para> - - <para>1. green - stage 1 (receiving request token)</para> - - <para>2. yellow - stage 2 (authentication)</para> - - <para>3. blue - stage 3 (receiving access token)</para> - - <para>4. red - stage 4 (get protected resource)</para> - </section> - - <section> - <title>Token Alive Time</title> - - <para>Alive time for tokens can be set using the parameter - tokenAliveTime.</para> - - <programlisting>&lt;value-param&gt; - &lt;!-- this parameter MUST be set in minutes --&gt; - &lt;name&gt;tokenAliveTime&lt;/name&gt; - &lt;value&gt;300&lt;/value&gt; -&lt;/value-param&gt;</programlisting> - </section> - - <section> - <title>Token Cleaner Timeout</title> - - <para>There is special component cleaner on consumer side, it starts, by - default, every 5 minutes and checks all tokens. If it finds token with - expired time it removes it from the storage. Token cleaner timeout (how - often it must run) can be also set in the configuration:</para> - - <programlisting>&lt;component&gt; - &lt;type&gt;org.exoplatform.ws.security.oauth.impl.OAuthTokenCleanerImpl&lt;/type&gt; - &lt;init-params&gt; - &lt;value-param&gt; - &lt;!-- this parameter MUST be set in minutes --&gt; - &lt;name&gt;tokenCleanerTimeout&lt;/name&gt; - &lt;value&amp;#623;&lt;/value&gt; - &lt;/value-param&gt; - &lt;/init-params&gt; - &lt;/component&gt;</programlisting> - </section> - </section> -</chapter> Deleted: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/rest-migration-to-jsr311.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/rest-migration-to-jsr311.xml 2010-08-05 13:44:26 UTC (rev 2886) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/rest-migration-to-jsr311.xml 2010-08-05 14:37:10 UTC (rev 2887) @@ -1,327 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id = "WS.RESTMigrationJSR311"> - <?dbhtml filename="ch-rest-migration-to-jsr311.html"?> - - <title>REST Migration to jsr311</title> - - <important> - <para>The new implementation of the REST engine respects the jsr311 - specification.</para> - </important> - - <section> - <title>REST service structure:</title> - - <itemizedlist> - <listitem> - <para>REST service must be represented by Java class that has @Path - annotation, it calls <command>root resource</command>. In some cases - class may have not @Path, about this classes see in Sub-Resource - Locators section. Root resource class may contain <command>Resource - Methods</command>, <command>Sub-Resource Methods</command> and - <command>Sub-Resource Locators</command>. Root resource MUST contain - at least one of it. </para> - - <para>1. <command>Resource Method</command> it is method that contains - HTTP method annotation, e.g. @GET, @POST, etc. and it does not contain - @Path annotation. </para> - - <para>2. <command>Sub-Resource Method</command> it is method that - contains HTTP method annotation and @Path annotation. Sub-Resource - Locator it is method that does not contain HTTP method annotation but - contains @Path annotation. </para> - - <para>3. <command>Sub-Resource Locator </command>can't process request - directly but it can produce Object (Resource) and that object can - process request or has <command>Sub-Resource Locator</command> that - can produce other Resource.Other important part @Consumes and - @Produces annotations. These annotations can be used at classes and - methods. Annotation on method override annotation on class.</para> - </listitem> - - <listitem> - <para>Annotated method parameters @PathParam, @QueryParam, @FormParam, - @HeaderParam, @Matrix, @CookieParam, @Context annotation must be - (Description of this annotation in jsr311 specification or jsr311-api - javadoc): </para> - - <para>1. String </para> - - <para>2. Primitive type, except char </para> - - <para>3. Has constructor with single string arguments </para> - - <para>4. Has static valueOf method with single string argument </para> - - <para>5. Be List, Set or SortedSet with items described in first four - points</para> - </listitem> - - <listitem> - <para>Not annotated method parameter or <command>Entity - Parameter</command>. </para> - - <para>1. Must be not more then one </para> - - <para>2. <command>Sub-Resource Locator</command> MUST NOT have - <command>Entity Parameter</command>. </para> - - <para>3. If <command>Resource Method</command> or - <command>Sub-Resource Method</command> contains at least one parameter - with @FormParam annotation then <command>Entity Parameter</command> - MUST be MultivaluedMap&lt;String, String&gt; only.</para> - </listitem> - - <listitem> - <para>Method return type. Resource method (<command>Resource - Method</command> or <command>Sub-Resource Method</command>) may return - void,javax.ws.rs.core.Response,javax.ws.rs.core.GenericEntity or other - Java type. If void type returned ot returned object is null then 204 - HTTP status will be set for response otherwise 200 status will be - used. With javax.ws.rs.core.Response response can be set by service - developer.</para> - </listitem> - - <listitem> - <para>Reading/Writing Entity done via - <command>EntityProvider</command>. Each - <command>EntityProvider</command> can require precise preset media - type of entity, for example JsonEntityProvider require 'Content-Type' - and/or 'Accept' header set as application/json. REST engine supports - next entity provider:</para> - - <table> - <title></title> - - <tgroup cols="3"> - <thead> - <row> - <entry align="center">Provider class</entry> - - <entry align="center">Media Type</entry> - - <entry align="center">Java Type</entry> - </row> - </thead> - - <tbody> - <row> - <entry>ByteEntityProvider</entry> - - <entry>*/*</entry> - - <entry>byte[]</entry> - </row> - - <row> - <entry>DataSourceEntityProvider</entry> - - <entry>*/*</entry> - - <entry>javax.activation.DataSource</entry> - </row> - - <row> - <entry>DOMSourceEntityProvider</entry> - - <entry>application/xml,application/xhtml+xml,text/xml</entry> - - <entry>javax.xml.transform.dom.DOMSource</entry> - </row> - - <row> - <entry>FileEntityProvider</entry> - - <entry>*/*</entry> - - <entry>java.io.File</entry> - </row> - - <row> - <entry>MultivaluedMapEntityProvider</entry> - - <entry>application/x-www-form-urlencoded</entry> - - <entry>MultivaluedMap&lt;String, String&gt;</entry> - </row> - - <row> - <entry>MultipartFormDataEntityProvider</entry> - - <entry>multipart/*</entry> - - <entry>java.util.Iterator&lt;org.apache.commons.fileupload.FileItem&gt;</entry> - </row> - - <row> - <entry>InputStreamEntityProvider</entry> - - <entry>*/*</entry> - - <entry>java.io.InputStream</entry> - </row> - - <row> - <entry>ReaderEntityProvider</entry> - - <entry>*/*</entry> - - <entry>java.io.Reader</entry> - </row> - - <row> - <entry>SAXSourceEntityProvider</entry> - - <entry>application/xml,application/xhtml+xml,text/xml</entry> - - <entry>javax.xml.transform.sax.SAXSource</entry> - </row> - - <row> - <entry>StreamSourceEntityProvider</entry> - - <entry>application/xml,application/xhtml+xml,text/xml</entry> - - <entry>javax.xml.transform.stream.StreamSource</entry> - </row> - - <row> - <entry>StringEntityProvider</entry> - - <entry>*/*</entry> - - <entry>java.lang.String</entry> - </row> - - <row> - <entry>StreamOutputEntityProvider</entry> - - <entry>*/*</entry> - - <entry>NOTE for writing data only</entry> - </row> - - <row> - <entry>JsonEntityProvider</entry> - - <entry>application/json</entry> - - <entry>Object (simple constructor, get/set methods)</entry> - </row> - - <row> - <entry>JAXBElementEntityProvider</entry> - - <entry>application/xml,application/xhtml+xml,text/xml</entry> - - <entry>javax.xml.bind.JAXBElement</entry> - </row> - - <row> - <entry>JAXBObjectEntityProvider</entry> - - <entry>application/xml,application/xhtml+xml,text/xml</entry> - - <entry>Object (simple constructor, get/set methods)</entry> - </row> - </tbody> - </tgroup> - </table> - </listitem> - </itemizedlist> - </section> - - <section> - <title>Migration Examples</title> - - <para>EXAMPLE #1</para> - - <para><command>Old code</command></para> - - <programlisting>package org.exoplatform.services.rest.example; - -import org.exoplatform.services.rest.HTTPMethod; -import org.exoplatform.services.rest.URITemplate; -import org.exoplatform.services.rest.URIParam; -import org.exoplatform.services.rest.container.ResourceContainer; -import org.exoplatform.services.rest.transformer.StringOutputTransformer; -import org.exoplatform.services.rest.OutputTransformer; -import org.exoplatform.services.rest.Response; - -@URITemplate("/a/{1}/b") -public class Resource implements ResourceContainer { - - @HTTPMethod("GET") - @URITemplate("{2}") - @OutputTransformer(StringOutputTransformer.class) - public Response m0(@URIParam("1") String param1, @URIParam("2") String param2) { - Response resp = Response.Builder.ok(param1+param2, "text/plain").build(); - return resp; - } -}</programlisting> - - <para><command>New code</command></para> - - <programlisting>import javax.ws.rs.GET; -import javax.ws.rs.Path; -import javax.ws.rs.PathParam - -@Path("/a/{1}/b") -public class Resource implements ResourceContainer { - @GET - @Path("{2}") - @Produces("text/plain") - public String m0(@PathParam("1") String param1, @PathParam("2") String param2) { - return path1+path2; - } -}</programlisting> - - <para>EXAMPLE #2</para> - - <para><command>Old code</command></para> - - <programlisting>import org.exoplatform.services.rest.HTTPMethod; -import org.exoplatform.services.rest.InputTransformer; -import org.exoplatform.services.rest.Response; -import org.exoplatform.services.rest.URITemplate; -import org.exoplatform.services.rest.container.ResourceContainer; -import org.exoplatform.ws.frameworks.json.transformer.Json2BeanInputTransformer; - -public class Resource implements ResourceContainer { - @HTTPMethod("POST") - @URITemplate("/") - @InputTransformer(Json2BeanInputTransformer.class) - public Response m0(Book book) { - // do something with bean - return Response.Builder.noContent().build(); - } -}</programlisting> - - <para><command>New code</command></para> - - <programlisting>import javax.ws.rs.POST; -import javax.ws.rs.Path; -import javax.ws.rs.Consumes; - -@Path("/") -public class Resource implements ResourceContainer { - @POST - @Consumes("application/json") - public void m0(Book book) { - // do something with bean - } -}</programlisting> - </section> - - <section> - <title>Support for javax.ws.rs.core.Application</title> - - <para>Since version exo-ws-2.0.1 add support for class - javax.ws.rs.core.Application. It gives possibility to setup services and - provider life-cycle to singleton or per-request mode. For details see - JAX-RS specification, chapter 2. Subclass of Application should be - configured as component of exo-container.</para> - </section> -</chapter> Deleted: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/soap-service-tutorial.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/soap-service-tutorial.xml 2010-08-05 13:44:26 UTC (rev 2886) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/soap-service-tutorial.xml 2010-08-05 14:37:10 UTC (rev 2887) @@ -1,247 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="WS.SOAPTutorial"> - <?dbhtml filename="ch-soap-service-tutorial.html"?> - - <title>SOAP Service Tutorial</title> - - <section> - <title>Introduction</title> - - <para>In this tutorial you will learn how you can use JSR 181 to expose - your Exo Container components as web services.</para> - - <para>The steps given below have been tested with eXo WS samples 2.0.2 - under Tomcat 6.0.16. It uses the WS tomcat bundle.</para> - - <para>You can use maven build within "ws/tags/2.0.2/application" to deploy - this sample application configuration:</para> - - <programlisting>mvn clean install -f product-exo-ws-as-tomcat6.xml antrun:run</programlisting> - </section> - - <section> - <title>Add JSR 181 support to the deployed application</title> - - <para>The JSR181 support does not come by default in portal.</para> - - <para>The WS example tomcat bundle, which you can deploy with provided - command above, has already all necessary libraries and SOAP servlet - declarations.</para> - - <para>For any other bundles you have to done the two steps below.</para> - - <section> - <title>Add dependencies</title> - - <para>First you need to add the necessary dependencies inside - exo-tomcat/lib</para> - - <para>The required artifacts are :</para> - - <itemizedlist> - <listitem> - <para>exo.ws.soap.cxf.jsr181-2.0.2.jar</para> - </listitem> - - <listitem> - <para>exo.ws.application.soap.cxf.samples-2.0.2.jar</para> - </listitem> - - <listitem> - <para>cxf-rt-transports-http-2.1.2.jar</para> - </listitem> - - <listitem> - <para>cxf-api-2.1.2.jar</para> - </listitem> - - <listitem> - <para>cxf-rt-core-2.1.2.jar</para> - </listitem> - - <listitem> - <para>cxf-common-utilities-2.1.2.jar</para> - </listitem> - - <listitem> - <para>wsdl4j-1.6.1.jar</para> - </listitem> - - <listitem> - <para>geronimo-jaxws_2.1_spec-1.0.jar</para> - </listitem> - - <listitem> - <para>geronimo-ws-metadata_2.0_spec-1.1.2.jar</para> - </listitem> - - <listitem> - <para>cxf-rt-frontend-jaxws-2.1.2.jar</para> - </listitem> - - <listitem> - <para>cxf-rt-frontend-simple-2.1.2.jar</para> - </listitem> - - <listitem> - <para>cxf-rt-bindings-soap-2.1.2.jar</para> - </listitem> - - <listitem> - <para>XmlSchema-1.4.2.jar</para> - </listitem> - - <listitem> - <para>cxf-rt-databinding-jaxb-2.1.2.jar</para> - </listitem> - - <listitem> - <para>jaxb-impl-2.1.7.jar</para> - </listitem> - - <listitem> - <para>cxf-tools-common-2.1.2.jar</para> - </listitem> - - <listitem> - <para>cxf-rt-ws-addr-2.1.2.jar</para> - </listitem> - - <listitem> - <para>saaj-api-1.3.jar</para> - </listitem> - </itemizedlist> - </section> - - <section> - <title>Configure CXF servlet</title> - - <para>Edit YOUR_APPLICATION.war/WEB-INF/web.xml and add the CXF servlet - :</para> - - <programlisting>&lt;servlet&gt; - &lt;servlet-name&gt;SOAPServlet&lt;/servlet-name&gt; - &lt;display-name&gt;SOAP Servlet&lt;/display-name&gt; - &lt;servlet-class&gt;org.exoplatform.services.ws.impl.cxf.transport.http.SOAPServlet&lt;/servlet-class&gt; - &lt;/servlet&gt; - - &lt;servlet-mapping&gt; - &lt;servlet-name&gt;SOAPServlet&lt;/servlet-name&gt; - &lt;url-pattern&gt;/soap/services/*&lt;/url-pattern&gt; - &lt;/servlet-mapping&gt;</programlisting> - - <important> - <para>alternatively, you could bundle cxf in a separate app, but make - sure ws-examples.war starts before it</para> - </important> - </section> - </section> - - <section> - <title>Write the Web Service class</title> - - <para>We have a tiny sample to demonstrate called : - TicketOrderService.</para> - - <para>Following JSR 181, it is now just a matter of annotating a class to - create a Web Service. The main idea is the your interface has to extends - extends AbstractSingletonWebService.</para> - - <programlisting>@WebService -public interface TicketOrderService extends AbstractSingletonWebService { - - /** - * @param departing departing place. - * @param arriving arriving place. - * @param departureDate departure date. - * @param passenger passenger. - * @return ticket order. - */ - public String getTicket(String departing, String arriving, Date departureDate, String passenger); - - /** - * @param confirmation confirm or not. - */ - public void confirmation(boolean confirmation); - -}</programlisting> - - <programlisting>@WebService(serviceName = "TicketOrderService", - portName = "TicketOrderServicePort", - targetNamespace = "http://exoplatform.org/soap/cxf") -public class TicketOrderServiceImpl implements TicketOrderService { - - /** - * Logger. - */ - private static final Log LOG = ExoLogger.getLogger(TicketOrderServiceImpl.class); - - /** - * Ticket. - */ - private Ticket ticket; - - /** - * @param departing departing place. - * @param arriving arriving place. - * @param departureDate departure date. - * @param passenger passenger. - * @return ticket order. - */ - public String getTicket(String departing, String arriving, Date departureDate, String passenger) { - ticket = new Ticket(passenger, departing, arriving, departureDate); - LOG.info(ticket); - return String.valueOf(ticket.getOrder()); - } - - /** - * @param confirmation confirm or not. - */ - public void confirmation(boolean confirmation) { - LOG.info("Confirmation : " + confirmation + " for order '" + ticket.getOrder() + "'."); - } - -}</programlisting> - - <para>To test quickly, you can simply grab the jar on eXo repository and - deploy within your application.</para> - </section> - - <section> - <title>Configure the component</title> - - <programlisting>&lt;configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_0.xsd http://www.exoplatform.org/xml/ns/kernel_1_0.xsd" - xmlns="http://www.exoplatform.org/xml/ns/kernel_1_0.xsd"&gt; - &lt;component&gt; - &lt;type&gt;org.exoplatform.services.ws.soap.jsr181.TicketOrderServiceImpl&lt;/type&gt; - &lt;/component&gt; -&lt;/configuration&gt;</programlisting> - </section> - - <section> - <title>Verify it works.</title> - - <para>Start server.</para> - - <para>Execute script at - ws/tags/2.0.2/application/java/services/samples/soap/client to test - service</para> - - <programlisting>run.sh</programlisting> - - <para>and watch for this in the logs:</para> - - <programlisting>Sep 3, 2009 5:21:13 PM org.apache.cxf.endpoint.ServerImpl initDestination -INFO: Setting the server's publish address to be /TicketOrderService/TicketOrderServicePort -03.09.2009 17:21:13 *INFO * [http-8080-1] ExoDeployCXFUtils: The webservice '/TicketOrderService/TicketOrderServicePort' has been published SUCCESSFUL! (ExoDeployCXFUtils.java, line 190) -03.09.2009 17:21:13 *INFO * [http-8080-1] WebServiceLoader: New singleton WebService '/TicketOrderService/TicketOrderServicePort' registered. (WebServiceLoader.java, line 95) -03.09.2009 17:21:27 *INFO * [http-8080-1] TicketOrderServiceImpl: Ticket {, , , null, 1251991287079} (TicketOrderServiceImpl.java, line 57) -03.09.2009 17:21:27 *INFO * [http-8080-1] TicketOrderServiceImpl: Confirmation : false for order '1251991287079'. (TicketOrderServiceImpl.java, line 65)</programlisting> - - <para>Now, your service is started and you can retrieve the WSDL at : - <uri>http://localhost:8080/ws-examples/soap/services/TicketOrderService/TicketOrderServicePort?wsdl</uri></para> - </section> -</chapter> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws.xml 2010-08-05 13:44:26 UTC (rev 2886) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws.xml 2010-08-05 14:37:10 UTC (rev 2887) @@ -12,43 +12,13 @@ <xi:include href="ws/introduction-to-rest.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="ws/rest-service-tutorial.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="ws/rest-migration-to-jsr311.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="ws/groovy-scripts-as-rest-services.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="ws/rest-framework.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="ws/soap-service-tutorial.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="ws/central-authentication-service-configuration.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="ws/kerberos-sso-on-active-directory.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="ws/oauth.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="ws/cometd.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="ws/cometd-cluster.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="ws/framework-for-cross-domain-ajax.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="ws/cometd-cluster-bench.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="ws/javascript-webdav-library.xml" - xmlns:xi="http://www.w3.org/2001/XInclude" /> - </part>