jAPS 2.0 entando - Plugin SOA-Content

Do It The jAPS Way

Eugenio Santoboni

Reviser 

AgileTec s.r.l.

<e.santoboni@agiletec.it>

William Ghelfi

Reviser 

Tzente s.r.l.

<w.ghelfi@tzente.it>

Stefano Puddu

Redattore della prima versione italiana 

AgileTec s.r.l.

<s.puddu@agiletec.it>

Matteo Minnai

English translation and adaption 

Tzente s.r.l.

<s.puddu@agiletec.it>

Copyright © 2010 Tzente s.r.l.

Legal Notice

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the Appendix entitled "GNU Free Documentation License".

The copyright holders make no representation about the suitability of this Document for any purpose. It is provided “as is” without expressed or implied warranty. If you modify this Document in any way, identify your resulting Document as a variant of this Document.

2011-02-24

Revision History
Revision 1.1	2011-02-24	MEM
Revision for the jAPS 2.0 entando version 2.2.0
Revision 1.0	2010-02-17	MEM
First public release

Abstract

The aim of this document is to give a comprehensive description of the plugin SOA-Content.

---

Table of Contents

1. Scope of the document

Introduction

Target audience

Prerequisites

Resources

2. Plugin characteristics

Functionalities

Adding an external content

Remote request of a content

3. Plugin installation and integration

Plugin installation and integration

Technical characteristics

Package description

Integration in a production environment.

Installation in a development environment

4. SOA-Content plugin configuration

SOA-Content plugin configuration

List of Tables

2.1. Plugin compatibility

Chapter 1. Scope of the document

Table of Contents

Introduction

Target audience

Prerequisites

Resources

Introduction

The aim of this document is to fully describe the structure of the SOA-Content (jpwscontent) plugin.

Target audience

This document is for those who want to know more about the jpwscontent plugin functionalities and are considering to install it in a production or development environment with the Eclipse IDE. This document is aimed at system administrators (responsible for jAPS 2.0 entando installations) and Java developers (with a basic comprehension of the jAPS 2.0 entando framework).

Prerequisites

In order to take maximum advantage from the present document, it is necessary to have a basic knowledge about: the Java platform, the Eclipse IDE development environment, the Apache Tomcat servlet container, the PosgreSQL DBMS and the jAPS 2.0 entando framework. The reading of the jAPS 2.0 Plugin Pattern is mandatory.

Resources

Additional informations may be obtained through the official mailing-lists:

• <japs-platform@googlegroups.com>, "japs-platform" Google Group, the jAPS 2.0 entando official Mailing List

Is it also possible to refer to the documentation found in the:

jAPS 2.0 entando Project - Developer Website

Chapter 2. Plugin characteristics

Table of Contents

Functionalities

Adding an external content

Remote request of a content

The SOA-Content plugin allows contents to be imported or exported through a web service.

Two methods can be invoked:

• the first that allows a client to add a content to the system.

• the last one allows a client to query a content given its ID.

Table 2.1. Plugin compatibility

Code	Name	Type	Plugin version	jAPS 2.0 entando version
jpwscontent	SOA-Content	Modification	1.2	2.2.0 -
jpwscontent	SOA-Content	Modification	1.1	2.0.10
jpwscontent	SOA-Content	Modification	1.0	2.0.8

Functionalities

This module provides the all the logic needed to exchange jAPS contents with third party applications.

More specifically two methods are exposed through the wsdl interface: addContent and getContent.

Adding an external content

Using the service method addContent it is possible to add an external content with all its resources to the jAPS 2.0 entando CMS contents.

To add an external content it is sufficient to create a WsContentEnvelope object that maps, in the form of a XML string, the content to add to the CMS. When the operation is completed the system returns the proper result code. Note: the content is added directly to the public contents.

If the content to add has referenced resources, these must be added to the WsContentEnvelope in the form of array of WsResource objects. If the receiving portal has resources or files sharing the same name or ID of the envelope objects, they will be automatically renamed with a new ID.

Remote request of a content

Using the service method getContent is it possible to ask for a content (and its resources) of the jAPS 2.0 entando CMS.

The system will return an object WsContentEnvelope containing the XML that maps the requested content. The references of the content, if present, are returned in a array of WsResource objects.

Chapter 3. Plugin installation and integration

Table of Contents

Plugin installation and integration

Technical characteristics

Package description

Integration in a production environment.

Installation in a development environment

Plugin installation and integration

Technical characteristics

JpWSContent is a Modification plugin because, in the installation process, it requires the modification of the Deployment Descriptor contained in the web.xml, for the use of the new servlets.

Package description

The package of the plugin contains all the needed directories ( doc ed src and the Readme file) as required by the document jAPSPlugin Pattern.

Moreover the src directory is structured as follows:

• Directory java. directory. It contains the source files and the test suites of the plugin.

  Directory webapp. It contains the configuration files nedded by Spring, Axis and the wsdl file.

Integration in a production environment.

From now on we refer to the application in the production environment where the plugin is going to be deployed as myportal. We also refer to the compressed file containing the all the plugin elements as 'package' or 'plugin package', and 'system' is always referred to the jAPS 2.0 entando framework installation and not to the hosting operating system.

To perform the installation in a production environment based on the jAPS 2.0 entando compatible with this plugin, please follow this procedure carefully:

1. Stop the servlet container before proceeding with the installation steps.

2. Modify the file web.xml and insert the code below after the last declaration of the last servlet

   	
   	  <servlet>
   	    <display-name>Apache-Axis Servlet</display-name>
   	    <servlet-name>AxisServlet</servlet-name>
   	    <servlet-class>org.apache.axis.transport.http.AxisServlet</servlet-class>
   	  </servlet>
   	  <servlet-mapping>
   	    <servlet-name>AxisServlet</servlet-name>
   	    <url-pattern>/servlet/AxisServlet</url-pattern>
   	  </servlet-mapping>
   	  <servlet-mapping>
   	    <servlet-name>AxisServlet</servlet-name>
   	    <url-pattern>*.jws</url-pattern>
   	  </servlet-mapping>
   	  <servlet-mapping>
   	    <servlet-name>AxisServlet</servlet-name>
   	    <url-pattern>/services/*</url-pattern>
   	  </servlet-mapping>
   	  <servlet>
   	    <display-name>Axis Admin Servlet</display-name>
   	    <servlet-name>AdminServlet</servlet-name>
   	    <servlet-class>org.apache.axis.transport.http.AdminServlet</servlet-class>
   	    <load-on-startup>100</load-on-startup>
   	  </servlet>
   	  <servlet-mapping>
   	    <servlet-name>AdminServlet</servlet-name>
   	    <url-pattern>/servlet/AdminServlet</url-pattern>
   	  </servlet-mapping>
   	
   	

3. Please ensure that the directory myportal/WEB-INF contains a file named server-config.wsdd; if not a copy is contained in the directory src/webapp/WEB-INF/plugins/jpwscontent of the plugin package. Copy server-config.wsdd in the directory myportal/WEB-INF. If the target directory already contains that file you only have to set the values in the service definition to your needs. This is typically done modifying the ns1:service and name="WsContentEndpoint" elements of the wsdd file.

4. Copy the content of the directory src/webapp/WEB-INF/lib of the plugin package into myportal/WEB-INF/lib/ within the server container.

5. Make sure that the directory myportal/webapp/WEB-INF/plugins exists, otherwise create it. Copy the content of the src/webapp/WEB-INF/plugins of the plugin package into myportal/WEB-INF/plugins/

6. Copy the content of the directory src/webapp/resources/plugins of the package into myportal/resources/plugins/ within the servlet container.

7. Is now possible to restart the servlet container.

Installation in a development environment

As a convention, we call the project where the plugin is about to be installed myproject; all the directories inside myproject are local to your Eclipse project.

To perform the installation in a production environment based on the jAPS 2.0 entando compatible with this plugin, please follow this procedure carefully:

1. Modify the file web.xml and insert the code below after the last declaration of the last servlet

   	  <servlet>
       <display-name>Apache-Axis Servlet</display-name>
       <servlet-name>AxisServlet</servlet-name>
       <servlet-class>org.apache.axis.transport.http.AxisServlet</servlet-class>
     </servlet>
     <servlet-mapping>
       <servlet-name>AxisServlet</servlet-name>
       <url-pattern>/servlet/AxisServlet</url-pattern>
     </servlet-mapping>
     <servlet-mapping>
       <servlet-name>AxisServlet</servlet-name>
       <url-pattern>*.jws</url-pattern>
     </servlet-mapping>
     <servlet-mapping>
       <servlet-name>AxisServlet</servlet-name>
       <url-pattern>/services/*</url-pattern>
     </servlet-mapping>
     <servlet>
       <display-name>Axis Admin Servlet</display-name>
       <servlet-name>AdminServlet</servlet-name>
       <servlet-class>org.apache.axis.transport.http.AdminServlet</servlet-class>
       <load-on-startup>100</load-on-startup>
     </servlet>
     <servlet-mapping>
       <servlet-name>AdminServlet</servlet-name>
       <url-pattern>/servlet/AdminServlet</url-pattern>
     </servlet-mapping>
   	

2. Please ensure that the directory myportal/WEB-INF contains a file named server-config.wsdd; if not a copy is contained in the directory src/webapp/WEB-INF/plugins/jpwscontent of the plugin package. Copy server-config.wsdd in the directory myportal/WEB-INF. If the target directory already contains that file you only have to set the values in the service definition to your needs. This is typically done modifying the ns1:service and name="WsContentEndpoint" elements of the wsdd file.

3. Copy the content of the directory src/webapp/WEB-INF/lib of the plugin package into myportal/WEB-INF/lib/ within the server container, with the exclusion of the file jAPSPlugin-jpwscontent-1.1.jar

4. Make sure that the directory myportal/webapp/WEB-INF/plugins exists, otherwise create it. Copy the content of the src/webapp/WEB-INF/plugins of the plugin package into myportal/WEB-INF/plugins/

5. Copy the content of the directory src/webapp/resources/plugins of the package in the directory myproject/WebContent/resources/plugins/.

6. Copy the contents of the directory src/java/main/com into myproject/src/com

7. Copy the content of the directory src/java/test/test into myproject/src/test

Once the steps above are completed, restart your Eclipse project and verify the presence of the new voices that this plugin adds in the administration area of this project.

To execute the test, it is necessary to run an instance of portal example (because it already contains predefined contents) with jpwscontent installed and the configured in a way that the system points to the test databases.

To make jAPS use the test database open the PortalExample/WebContent/META-INF/context.xml

• in the JNDI resources jdbc/portDataSource and jdbc/servDataSource modify the url of the databases the drivers point to specifying the appropriate name of the test database (PortalExampletestPort and PortalExampletestServ for PortalExample).

• in the same file, change the value of the configVersion from 'production' to 'test', as shown below: <Environment name="configVersion" value="test" type="java.lang.String" override="false" />

Warning: for safety reasons is not possible to delete contents through webservice request, so you have to clean manually the tables after the tests.

Chapter 4. SOA-Content plugin configuration

Table of Contents

SOA-Content plugin configuration

SOA-Content plugin configuration

This plugin does not require any configuration.