Welcome to the OW2 Siwpas™, Simple Web Profile Application Server, administration guide. If you are reading this document, probably you have downloaded and been using Siwpas application server for your enterprise applications. Thank you for downloading and using Siwpas.

1.1. About This Guide

This guide has been written for administrators and users of Siwpas. Administrators can learn how to configure and use Siwpas in a production environment. Users can learn how to create web applications using the Java™ Platform, Enterprise Edition 6 (Java EE 6) technologies.

We hope that this user guide helps you to increase your knowledge and understanding of Siwpas. We are sure that it will make usage of Siwpas a lot easier for you. Feedback is always welcome.

1.2. About OW2

OW2 is an independent, global, open-source software community. The mission of OW2 is to

a) promote the development of open-source middleware, generic business applications, cloud computing platforms and

b) foster a vibrant community and business ecosystem.

OW2 developments follow a flexible, component-based approach. These components range from specific software frameworks, protocols and applications through to integrated, service-oriented platforms for enterprise computing.

OW2 consortium is an independent non-profit organization open to companies, public organizations, academia and individuals. OW2 is an open organization.

OW2 is committed to growing a community of open source code developers. The organization is dedicated to the creation of new technology: original code development is one of its fundamental characteristics. OW2 champions the tenets of quality and usability of its software in the open source enterprise marketplace. It fosters a common technical architecture to be shared by its members and to facilitate the implementation of its technology by systems integrators and end-users.

The OW2 projects aim at facilitating the development, deployment and management of distributed applications with a focus on open source middleware and related development and management tools. In the open source software value chain, OW2 is positioned as an industry platform facilitating interaction between open source code Producers and open source code Consumers.

OW2 provides three types of services to its community. First, OW2 operates a technical infrastructure: delivering tools and collaborative services to project teams: the core of the platform is a forge, the application which technically supports the projects through a number of tools for the management of code contributions, versions, debugging, licenses, contributors, redistribution, etc. Second it provides community services: organizing activities and the decision-making process; OW2 is a catalyst for social and business interaction relying on five guiding principles: Openness, Fairness, Trust, Transparency and Independence. Third, it provides marketing services: helping build the community identity, brand and the projects' visibility essentially in three ways: creating collateral, organizing the community's presence at professional events and driving outbound communication.

1.3. About MechSoft Mechanical and Software Solutions

MechSoft Mechanical and Software Solutions has located in Ankara, capital city of Turkey. It has two different branches,

· Mechanical Group

· Software Group

About Mechanical Group

Mechanical group is the main distributor of well-known CAD/CAM products like "Alibre, Bricscad, hyperMill and thinkdesign" in Turkey. Moreover he has been developing projects related with mechanical engineering discipline.

About Software Group

Software Group mission is to provide an open source, high quality software products that are backed by the our technical experts and authorized partners. We are mainly specialized on Java Enterprise Edition and middleware technologies.

Siwpas is one of the our open source flagship product. Siwpas Enterprise Edition is tested and certified on open source and propietary stacks, and includes full commercial support. Siwpas Community Edition is backed by the open source community.

Software Group provides comprehensive services including Professional Support, Training, and Consulting around Siwpas Enterprise Edition.

1.4. Contact OW2

You can contact OW2 from,

OW2 Web Site	http://www.ow2.org
OW2 Techincal Platform	hotline@ow2.org
OW2 Service Desk	http://jira.ow2.org/browse/SERVICEDESK
OW2 Management Office	management-office@ow2.org

1.5. Contact MechSoft

You can contact MechSoft from,

MechSoft Web Site	http://mechsoft.com.tr
MechSoft Phone Number	+90 312 482 59 49
MechSoft Fascimile	+90 312 482 54 39
MechSoft Mail	info@mechsoft.com.tr
Siwpas Information	info@siwpas.mechsoft.com.tr
Siwpas Sales	sales@siwpas.mechsoft.com.tr
Siwpas Support	support@siwpas.mechsoft.com.tr
Siwpas Partners	partners@siwpas.mechsoft.com.tr

Legal Notices

Siwpas is trademark of the MechSoft Mechanical and Software Solutions. Apache and Apache related project names are trademark of The Apache Software Foundation. Oracle and Java are registered trademarks of Oracle and/or its affiliates. All other marks mentioned may be trademarks or registered trademarks of their respective owners

No part of this document may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means of electronic, mechanical, recording, or otherwise, without the prior written permission of MechSoft Mechanical and Software Solutions. Please note that the content in this document is protected under copyright law even if it is not distributed with software that includes an end user license agreement.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. MECHSOFT MECHANICAL AND SOFTWARE SOLUTIONS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.

Thanks to OW2 Consortium

Siwpas has been developing under the OW2 Consortium. Thanks to OW2 Consortium to provide as a excellent techincal infrastructure and help us to grow Siwpas Community!

Thanks to Apache Software Foundation

The Siwpas could not exist without the Apache Software Foundation (ASF)’ Java EE enterprise grade projects. Thanks to ASF for making available open-source software used in developing Siwpas.

Some information in this document are taken from the ASF Java EE projects’ documentation or web site.

2. Introduction

For administrators there are some important bits of information you should familiarize yourself with before starting out. This section serves as a brief introduction to some of the concepts and terminology behind the Siwpas application server.

2.1. Terminology

In the course of reading these documents, you'll run across a number of terms; some specific to Siwpas.

Keyword	Explanation
Siwpas	Simple Web Profile Application Server. Lightweight Java web application server.
Web Profile	JavaTM Platform, Enterprise Edition 6 (Java EE 6) Web Profile, a profile of the JavaTM Platform, Enterprise Edition 6 (Java EE 6) Specification that includes the web application related technologies.
Siwpas Web Server	Web server component of Siwpas. Siwpas web server is powered by Apache Tomcat.
Siwpas EJB Lite Server	Enterprise Java Beans(EJB) lite server component of Siwpas. Siwpas ejb lite server is powered by Apache OpenEJB.
Admin Console	Siwpas administration console.
Apache Tomcat	JSP and Servlet container. Developed by Apache Software Foundation(ASF)
Apache OpenEJB	EJB Specification Reference Implementation. Developed by ASF
Apache MyFaces	Java Server Faces Specification Reference Implementation. Developed by ASF
Apache OpenWebBeans	Context and Dependency Injection for the Java EE Platform Reference Implementation. Developed by ASF
Apache OpenJPA	Java Persistence API Reference Implementation. Developed by ASF
Apache Bean Validation	Bean Validation Specification Reference Implementation. Developed by ASF
WAR File	Web application archive file. Deployment unit for Siwpas.
Collapsed EAR	WAR file that also contains EJB beans.
Java Web Application	Web application that is deployed and run on applicable Java web server.
Web Application Context	Same as web application. Apache Tomcat specific term.
JMX	Java Management Extension technology. Provides management view of java objects.

2.2. About Siwpas

Siwpas (pronounced as Simple Web Profile Application Server) is a lightweight Java application server platform for running enterprise quality Java™ Platform, Enterprise Edition 6 (Java EE 6) web applications. Siwpas integrates ASF Java EE 6 related projects for providing a Java EE Web Profile compatible runtime platform.

2.3. Why Siwpas, Why Another Server?

Good question :)

Nowadays, a huge number of application developers and enterprise companies want to use lightweight application servers for deploying and running their web applications. They do not want to use heavyweight Java EE Servers that are fully compliant with Java EE Specifications. They want to manage light weight, cloud environment friendly servers. Nonetheless, they also need more technology stack for implementing their web based applications, such as "JPA, JSF, JTA , EJB etc."

Moreover, most of them deploy their critical enterprise web applications into the Apache Tomcat in their production systems.

Siwpas is aimed at providing a lightweight application server runtime based on Apache Tomcat 7. It also fills web applications technology requirements via ASF Java EE projects. In summary, Siwpas translates Apache Tomcat 7 into a more powerful enterprise web server.

The benefits of using Siwpas can be listed as follows:

· It has a lightweight but powerful runtime environment,

· It is based on the very-well known JSP and Servlet Container, Apache Tomcat 7,

· It consists of Web Profile Specification technology stack,

· It consists of powerful, commerical quality ASF Java EE Projects,

· It is an open source project,

· It is supported by MechSoft (7x24 enterprise support),

· It is light and will be always light,

· It has a very cool JSF based administration console.

2.4. Siwpas License

Siwpas is an open source project and released under the GNU LGPL license.

2.5. Siwpas Professional Support

Any company or anybody can provide professional support for Siwpas. Here is the current list of companies that provide professional support for Siwpas,

MechSoft : Siwpas is supported by the MechSoft according to the subscription plan. There are two different subscription plans for Siwpas, "Basic Support", "Standard Support" and "Enterprise Support".

Generally, when you get subscription license, you are able to get,

· Product Updates,

· Security Patches,

· Hot Fixes,

· Phone, Mail and Web based support,

· Help Contracts,

· Custom Features,

· .... and more.

You can get more information from Siwpas Sales Page to get more information about Siwpas' subscription plans.

2.6. Web Profile Compliance

Currently Siwpas does not claim compliance with Java EE Web Profile Specification because it has not been tested with Java EE Web Profile TCK. This does not mean that Siwpas will never be certified as a Web Profile Compliance application server. In order to test Siwpas with Java EE Web Profile TCK, MechSoft has to be a licensee of Oracle and we are discussing a reasanable way to obtain this TCK. As mentioned in the above paragraphs, with the exception of Apache OpenEJB, ASF Java EE projects are TCK compliant with their respective specificiations. Apache OpenEJB has certified in Apache Geronimo application server.

2.6.1. JSR-299 and JSR-303 TCKs

Siwpas has passed “JSR-299 Web Profile TCK” and “JSR-303 TCK” succesfully. Therefore, Siwpas provides JSR-299 and JSR-303 compatible CDI and Validation runtime.

JSR-299 (Context and Dependency Injection fort he Java EE Platform) and JSR-303 (Bean Validation) TCKs are licensed under ASL v2. Therefore we are able to test Siwpas via these TCKs.

TCK Locations	URL
BVAL TCK	http://community.jboss.org/wiki/BeanValidationTCK
CDI TCK	http://seamframework.org/Weld/CDITCKReleases

2.7. What is Web Profile?

Java EE Web Profile, a profile of Java EE 6 Specification that includes the web application related technologies.

According to the Java EE Web Profile specification, "The Web Profile is aimed at developers of modern web applications. Aiming "modern" web applications then implies offering a reasonably complete stack, composed of standard APIs, and out-of-the-box capability to address the needs of a large class of web applications".

You can download and get more information from the Java Community Process(JCP) page of the specification. JSR 316: JavaTM Platform, Enterprise Edition 6 (Java EE 6) Specification.

Web profile contains the following technologies,

Keyword	Version
Servlet	3.0
Java Server Pages (JSP)	2.2
Expression Language	2.2
Debugging Support for Other Languages	1.0
Standard Tag Library for JSP	1.2
Java Server Faces	2.0
Common Annotations for the Java Platform	1.0
Enterprise Java Beans Lite	3.1
Java Transaction API	1.1
Java Persistence API	2.0
Bean Validation	1.0
Managed Beans	1.0
Interceptors	1.1
Context and Dependency Injection for Java EE	1.0
Dependency Injection for Java	1.0

2.8. Apache Software Foundation EE Projects

Siwpas uses ASF Java EE based projects for web profile components.

Following table shows Apache Java EE projects that are used (or powered by) in Siwpas

ASF Project Name	Web Profile Requirement
Apache Tomcat 7™	Servlet, JSP,EL and related components
Apache MyFaces 2™	Java Server Faces component
Apache OpenEJB™	Siwpas EJB Lite server is powered by OpenEJB. Support for EJB 3.1 Lite and related components
Apache OpenWebBeans™	Siwpas CDI container is powered by OpenWebBeans. Support for CDI.
Apache Bean Validation™	Validation component.
Apache OpenJPA™	Persistence API component.

2.9. Useful Links

While we've done our best to ensure that these documents are clearly written and easy to understand, we may have missed something. Provided below is some useful links in case you get stuck.

Site Explanation	URL
Siwpas Main Page	http://siwpas.mechsoft.com.tr
Siwpas OW2 Forge	http://forge.ow2.org/projects/siwpas
Siwpas Documents	http://siwpas.mechsoft.com.tr/docs
Siwpas User Forum	http://siwpas.mechsoft.com.tr/forum
Siwpas Bug Tracker	http://siwpas.mechsoft.com.tr/bugs
Siwpas Dev Mailing List	http://mail.ow2.org/wws/info/siwpas-dev
Siwpas User Mailing List	http://mail.ow2.org/wws/info/siwpas-user
Siwpas Source	http://forge.ow2.org/plugins/scmsvn/index.php?group_id=422

3. Getting Started

Siwpas is a free lightweight Java web server that is based on Apache Tomcat 7 that is the most widely used Open Source servlet and jsp container on the market. The server binary and source code(only community edition) distributions are available from the Siwpas downloads page.

Download Siwpas	URL
Siwpas Downloads	http://siwpas.mechsoft.com.tr/downloads

In this part, you will learn how to install SiwpasEnterprise-x.y.z-GA.zip and deploy web applications into its runtime environment. For open source developers, this section also outlines how to build installable Siwpas binary from the source code of Siwpas.

3.1. Installing Prerequisite Software

Before you use Siwpas, your environment must have Java JDK or Java JRE. Currently Siwpas only works with with Java JDK/JRE 1.6 or greater.

Ensure that the <java_home>/bin directory is added to the PATH system variable and both the JAVA_HOME and JRE_HOME system variables are defined after installing JVM.

Steps to install JDK/JRE,

· Download the Java SE Runtime Environment (JRE), release version 6.0 or later, from

Download JDK	URL
Location	http://www.oracle.com/technetwork/java/javase/downloads/index.html

· Install the JDK/JRE according to the instructions included with the release.

· Set an environment variable named JRE_HOME to the pathname of the directory into which you installed the JDK/JRE, e.g. c:\jre6.0 (c:\jdk6.0) or /usr/local/java/jre6.0 (/usr/local/java/jdk6.0).

3.2. Download and Install the Siwpas Binary Distribution

Depending on the platform you plan to install and run Siwpas download the appropriate installation image. Select the appropriate file compression format for your operating system (.zip, .tar.gz) by clicking directly on the link, download it and expand the binary to your hard drive in a new directory.

Unpack the binary distribution into a convenient location so that the distribution resides in its own directory (conventionally named "SiwpasEnterprise(Community)-[version]"). For the purposes of the remainder of this document, the symbolic name "$SIWPAS_HOME" is used to refer to the full pathname of the release directory.

3.2.1. Directory Structure

Installing the Siwpas distribution creates SiwpasEnterprise-1.0.0-GA directory which contains server start scripts, JARs, web ans ejb server configuration sets and working directories.

Figure 1: The Directory Structure of SiwpasEnterprise-1.0.0-GA

Throughout the book we will refer to the top-level SiwpasEnterprise-1.0.0-GA directory as the SIWPAS_HOME directory.

Below table explains Siwpas directory structure content.

Directory	Description
bin	Contains several scripts and startup jars.
conf	Contains configuration files.
endorsed	Contains endorsed libraries.
lib	Contains Siwpas all library jars.
licenses	Contains Siwpas Enterprise License
logs	Contains several log files of Siwpas.
txLog	If transaction recovery is enabled. Default is not enabled
temp	Siwpas temp directory.
webapps	Default web applications deployment directory.
work	Siwpas work directory.

3.2.2. Siwpas Configuration Files

The default Siwpas configuration file set is located in the $SIWPAS_HOME/conf directory.

· “catalina.policy”: The catalina.policy file is a place holder for Java2 security permissions. This file contains a default set of security policies to be enforced (by the

JVM) when Siwpas is executed with the "-security" option.

· “catalina.properties” : Defines properties used by the Tomcat.

· “context.xml”: Tomcat’ common context.xml file. The contents of this file will be loaded for each web application.

· “log4j.properties”: Log4j configuration file that is used by Siwpas EJB Server. You can also use this file for other log4j configurations.

· “logging.properties” : Tomcat Juli (Tomcat logging system based on Java Logging) configuration file.

· “openejb.xml” : Used by Siwpas EJB Server to configure OpenEJB. It configures EJB “Stateless, Stateful, Singleton” containers and default datasources.

· “server.xml” : Tomcat main configuration file.

· “openejb.properties”: Defines Siwpas EJB system properties. It is used by Siwpas EJB Server. You can define extra system properties to override default configuration. Each property is added to System properties.

· “siwpas-users.xml” : Siwpas provides default UserDatabase Realm based on file. This file contains realm’ users, groups and roles.

· “web.xml” : This document defines default values for all web applications loaded into this instance of Siwpas. As each application is deployed, this file is processed, followed by the "/WEB-INF/web.xml" deployment descriptor from your own applications.

3.2.3. Advanced Configuration - Multiple Siwpas Instances

In many circumstances, it is desirable to have a single copy of a Siwpas binary distribution shared among multiple users on the same server. To make this possible, you can set the $SIWPAS_BASE environment variable to the directory that contains the files for your 'personal' Siwpas instance.

When you use $SIWPAS_BASE, Siwpas will calculate all relative references for files in the following directories based on the value of $SIWPAS_BASE :

· bin - Only setenv.sh (*nix), setenv.bat (windows) and tomcat-juli.jar

· conf - Server configuration files (including server.xml)

· logs - Log and output files

· txLog – Transaction log file.

· webapps - Automatically loaded web applications

· work - Temporary working directories for web applications

· temp - Directory used by the JVM for temporary files (java.io.tmpdir)

Note that by default Siwpas will first try to load classes and JARs from $SIWPAS_BASE/lib and then $SIWPAS_HOME/lib. You can place instance specific JARs and classes (eg JDBC drivers) in $SIWPAS_BASE/lib whilst keeping the standard Siwpas JARs in $SIWPAS_HOME/lib.

If you do not set $SIWPAS_BASE, $SIWPAS_BASE will default to the same value as $SIWPAS_HOME, which means that the same directory is used for all relative path resolutions.

3.3. Start Up Siwpas

Siwpas is based on Apache Tomcat 7. If you have experienced with Tomcat 7, it is very easy to "start" Siwpas.

Siwpas can be started by executing the following commands:

Platform	Script
Windows	$SIWPAS_HOME\bin\startup.bat
Unix	$SIWPAS_HOME/bin/startup.sh

Figure 2 : Starting via “startup.bat”

Platform	Script
Windows	$SIWPAS_HOME\bin\siwpas.bat start
Unix	$SIWPAS_HOME/bin/siwpas.sh start

Figure 3 : Starting via “siwpas.bat start”

Above commands run Siwpas in a new window. If you wish to start Siwpas in a current window, you can use the following commands,

Platform	Script
Windows	$SIWPAS_HOME\bin\siwpas.bat run
Unix	$SIWPAS_HOME/bin/siwpas.sh run

Figure 4 : Starting via “siwpas.bat run”

Your output should be similar to that shown below and contain no error or exception messages:

Figure 5: Sample Start Command Result

If your output is similar to the above figure sequences, you are ready to use Siwpas. Shutting down the server is very easy, simply issue a Ctrl-C sequence in the console in which Siwpas was started. As an alternative way, you can use the shutdown.bat/shutdown.sh command.

After startup, the default web applications included with Siwpas will be available by visiting:

· http://localhost:8080/

If Siwpas has been started successfully, you will see the following page when you hit the above address,

Figure 6: Siwpas ROOT application

3.4. Shut Down Siwpas

Siwpas is based on Apache Tomcat 7. If you have experienced with Tomcat 7, it is very easy to "shutdown" Siwpas.

Siwpas can be shut down by executing the following commands:

Platform	Script
Windows	$SIWPAS_HOME\bin\shutdown.bat
Unix	$SIWPAS_HOME/bin/shutdown.sh

Figure 7 : Shutdown via “shutdown.bat”

Platform	Script
Windows	$SIWPAS_HOME\bin\siwpas.bat stop
Unix	$SIWPAS_HOME/bin/siwpas.sh stop

Figure 8 : Shutdown via “siwpas.bat stop”

Your output should be similar to that shown below and contain no error or exception messages:

Figure 7: Sample ShutDown Command Result

3.5. Running Siwpas as Windows Service

You can also run Siwpas as Windows Service. In the “bin” directory there are two scripts related with service operations

Script Name	Explanation
siwpas1.exe	It is a service application for running Siwpas as NT service.
siwpasw.exe	It is a GUI application for monitoring and configuring Siwpas services.

3.5.1. Siwpas1 Service Application

You can use the following command line arguments with “siwpas1.exe”,

Parameter	Description
//TS//	Run the service as console application. This is the default operation. It is called if the no option is provided. The ServiceName is the name of the executable without exe suffix, meaning Siwpas1.
//RS//	It is only called from service manager window.
//SS//	Stops the running Siwpas1 service.
//US//	Update service parameters.
//IS//	Installs the service.
//DS//	Stops the service if running and deletes.

There are some command line parameters that you can give while executing the siwpas1.exe commands.

Parameter Name	Description	Default Value
--Description	Service name description (maximum 1024 characters)	No default
--DisplayName	Service display name	Service name. For example, Siwpas1
--Install	Stops the running Siwpas1 service.	siwpas1.exe //RS//Siwpas1
--Startup	Service startup mode can be either auto or manual	manual
--DependsOn	List of services that this service depend on. Dependent services are separated using either # or ; characters	No default
--Environment	List of environment variables that will be provided to the service in the form key=value. They are separated using either # or ; characters	No default
--User	User account used for running executable. It is used only for StartMode java or exe and enables running applications as service under account without LogonAsService privilege.	No default
--Password	Password for user account set by --User parameter	No default
--JavaHome	Set a different JAVA_HOME than defined by JAVA_HOME environment variable	JAVA_HOME env. Variable
--Jvm	Use either auto or specify the full path to the jvm.dll. You can use the environment variable expansion here.	auto
--JvmOptions	List of options in the form of -D or -X that will be passed to the JVM. The options are separated using either # or ; characters.	No default
--Classpath	Set the Java classpath	No default
--JvmMs	Initial memory pool size in MB	No default
--JvmMx	Maximum memory pool size in MB	No default
--JvmSs	Thread stack size in KB	No default
--StartImage	Executable that will be run.	No default
--StartPath	Working path for the start image executable.	No default
--StartClass	Class that will be used for startup.	No default
--StartParams	List of parameters that will be passed to either StartImage or StartClass. Parameters are separated using either # or ; character.	No default
--StartMethod	Method name if differs then main	main
--StartMode	Can one of jvm java or exe	exe
--StopImage	Executable that will be run on Stop service signal.	No default
--StopPath	Working path for the stop image executable.	No default
--StopClass	Class that will be used on Stop service signal.	No default
--StopParams	List of parameters that will be passed to either StopImage or StopClass. Parameters are separated using either # or ; character.	No default
--StopMethod	Method name if differs then main	main
--StopMode	Can one of jvm java or exe	exe
--StopTimeout	Defines the timeout in seconds that procrun waits for service to exit gracefully.	No Timeout
--LogPath	Defines the path for logging	working path
--LogPrefix	jakarta_service	Defines the service log filename
--LogLevel	Defines the logging level and can be either error, info, warn or debug	İnfo
--StdOutput	Redirected stdout filename	No default
--StdError	Redirected stderr filename	No default

3.5.2. Installing Siwpas Windows Service

The safest way to manually install the service is to use the provided service.bat script. Administrator privileges are required to run this script. If necessary, you can use the /user switch to specify a user to use for the installation of the service.

On Windows Vista or any other operating system with User Account Control (UAC) you must either disable UAC or right-click on cmd.exe and select "Run as administrator" in order to run this script. If UAC is enabled neither being logged on with an Administrator account, nor using the /user switch is sufficient.

Figure 9 : Install the service named 'Siwpas1'

After this command, you will see the following output;

Figure 10 : Install the service named 'Siwpas1'

If you want to use “siwpas1.exe” , you have to use //IS// parameter. In this case you have to provide all parameters in command line.

See $SIWPAS_HOME/bin/service.bat to see how to give command line parameters to //IS// command.

After the servie has been installed succesfully, you can see the service in Administrator Tools/Services

Figure 11 : Siwpas1 Service

3.5.3. Starting The Service

After installing the service, you can start the service via 3 different ways

· Using siwpas1.exe,

· Using siwpas1w.exe monitor application,

· Using Administrator Tools/Services window.

Starting via siwpas1.exe

Figure 12 : Starting Service via siwpas1.exe

Starting via siwpas1w.exe

Figure 13 : Starting Service via siwpas1w.exe

Starting via Administration Tools/Services

Figure 14 : Starting Service via Administration Tools/Services

3.5.4. Removing Windows Service

To remove the service, you need to use the //DS// parameter. If the service is running it will be stopped and then deleted.

Figure 15 : Removing Siwpas1 Service

3.6. Open Siwpas Administration Console

Siwpas administration console is only available in Siwpas Enterprise Edition.

After you have installed Siwpas succesfully, you can open Siwpas Administration Console from

· http://localhost:8080/console

You will see a web page, similar to the following figure,

Figure 16 : Siwpas Administration Console

Default user name and password combination of the console application “admin:admin”.

3.7. Section Summary

In this chapter, we have seen how to install and start Siwpas application server. Siwpas installation is very simple. Download and extract Siwpas distribution into your server empty driver.

You can also run Siwpas as NT Services. This configuration is applicable for Windows OS only.

4. Siwpas Architecture

4.1. Siwpas Components

Siwpas (pronounced as Simple Web Profile Application Server) is a lightweight Java application server platform for developing enterprise quality Java EE web applications. Siwpas integrates above ASF Java EE based projects for providing a Java EE Web Profile compatible runtime platform (see Figure 17).

Figure 17 : Standard Siwpas Components

Siwpas has been built around Apache Tomcat version 7 Servlet & JSP Container. Apache Tomcat version 7.0 implements the Servlet 3.0 and JavaServer Pages 2.2 specifications from the Java Community Process. But standard Tomcat distribution does not include the following Java EE technologies,

· Java Server Faces,

· Java Persistence API,

· Context and Dependency Injection for the Java EE Platform,

· Dependency Injection for Java,

· Bean Validation,

· Managed Beans,

· Enterprise Java Beans Light, (EJB Light) Features,

Siwpas includes all of these technologies and allows running them together in the common environment, Apache Tomcat 7. To enable running these technologies together, Siwpas includes integration layer component that is responsible for integrating these components.

With Siwpas, no need to bundle each specific technology libraries with your web applications. All of those technologies are ready to use.

In other sections of this document, each component of Siwpas will be explained in more detailed.

5. Siwpas Web Server

Siwpas web server is based on the Apache Tomcat 7. We do not see a reason to document Tomcat related concepts. You can read the Tomcat documentation from,

Tomcat 7 Documentation	URL
Documentation For Tomcat	http://tomcat.apache.org/tomcat-7.0-doc/

In this part, we will talk about Siwpas specific configuration for Apache Tomcat.

5.1. Logging File Content

Siwpas adds some more logging configuration into the file “logging.properties.” These additions are necessary to restrict output of the logging.

Tomcat Logger File	Location
Tomcat Logging File Location	$SIWPAS_HOME/conf/logging.properties

Siwpas Console Related Log Configuration

Figure 19 : Administrator Console Related Log Configuration

Apache MyFaces Related Log Configuration

Figure 20 : Apache MyFaces Related Log Configuration

Commons Digester Related Log Configuration

Figure 21 : Apache Commons Digester Related Log Configuration

Apache Tomcat Related Log Configuration

Figure 22 : Apache Tomcat Related Log Configuration

5.2. Catalina System Properties File Content

For increasing the performance of Tomcat while deploying web applications, more skipping library jars have added to the “catalina.properties” file.

Catalina Properties File	Location
Catalina Properties File Location	$SIWPAS_HOME/conf/catalina.properties

Some of them are seen in the following figure,

Figure 22 : List of JAR files that should not be scanned for configuration information

5.2.1. Strict Servlet Compliance

As default Siwpas distribution, Siwpas has not configured as strict servlet compliance, i.e some of the Siwpas behaviours are not compatible with servlet specification. If you wish to use strict servlet compliance for Tomcat 7, you have to comment out “org.apache.catalina.STRICT_SERVLET_COMPLIANCE” parameter in the “catalina.properties” file.

Figure 23 : Configure Tomcat 7 as servlet compliance

For other catalina system properties and their explanations see

Description	URL
Catalina Props.	http://tomcat.apache.org/tomcat-7.0-doc/config/systemprops.html

6. Siwpas Enterprise Java Beans (EJB) Lite Server

Siwpas contains embeddable lightweight EJB Lite Server , powered by the “Apache OpenEJB” project. This section introduces you with EJB concepts and Siwpas EJB Lite Server (Siwpas ELS).

Siwpas EJB 3.1 Lite Server provides runtime environment that is described in “EJB 3.1 Specification Chapter 21- Runtime Enviornment, 21.1 EJB 3.1 Lite”. Nevertheless, Siwpas EJB Lite Server has not been tested with EJB 3.1 Lite Technology Compatibility Kit. (EJB 3 TCK) that is contained in Java EE Web Profile TCK. See Siwpas Web Profile Compliance section to get further information.

6.1. What is EJB?

From Enterprise Java Beans 3.1 Specification,

“The Enterprise JavaBeans architecture is a architecture for the development and deployment of component-based business applications. Applications written using the Enterprise JavaBeans architecture are scalable, transactional, and multi-user secure. These applications may be written once, and then deployed on any server platform that supports the Enterprise JavaBeans specification.”

You can reach the full EJB 3.1 specification from,

Description	URL
EJB 3.1 Specification	http://jcp.org/en/jsr/summary?id=318

In summary, The Enterprise JavaBeans architecture is the standard component architecture for building object-oriented business applications in the Java™ programming language.

6.2. What is EJB Lite?

According to the EJB 3.1 specification, EJB 3.1 server(container) must provide runtime environment for deploying and running EJB components. Run environments provide standard EJB APIs used by these EJB components. These APIs can be used by portable enterprise beans because the APIs are guaranteed to be available in all EJB 3.1 containers. The set of required APIs is divided into two categories,

· A complete set,

· A minimum set, a.k.a EJB 3.1 Lite.

A complete set must implement all EJB 3.1 APIs. EJB 3.1 Lite must implement a minimal subset of the EJB API. Here is the definition from EJB 3.1 specification,

“The EJB API is comprised of a large feature set with support for implementing business logic in a wide variety of enterprise applications. However, the full range of API contracts is not always crucial for all runtime environments. In addition, the breadth of the full API can present challenges for developers just getting started with Enterprise JavaBeans technology.

For these reasons this specification defines a minimal subset of the EJB API known as EJB 3.1 Lite. EJB 3.1 Lite is not a product. Rather, it is a proper subset of the full EJB 3.1 API that includes a small, powerful selection of EJB features suitable for writing portable transactional business logic. The definition of EJB 3.1 Lite gives vendors an option to implement only a portable subset of the EJB API within their product. The vastly reduced size of the feature set makes it suitable for inclusion in a wider range of Java products, many of which have much smaller installation and runtime footprints than a typical full Java EE implementation.

An EJB 3.1 Lite application is merely an EJB application whose EJB API usage falls within the EJB Lite subset. There are no special APIs defined only for EJB 3.1 Lite. Therefore, any EJB 3.1 Lite application can be deployed on any Java EE product that implements Enterprise JavaBeans technology, whether that product supports EJB 3.1 Lite or the full EJB API.”

Belows table shows EJB 3.1 Lite supported and not supported APIs. All EJB 3.1 Lite APIs are supported in Siwpas EJB 3.1 Lite Server.

Required APIs	Supported	Supported in Siwpas
Session beans (Stateful, Stateless, Singleton)	YES	YES
Message Driven Beans	NO	NO
2.x/1.x CMP/BMP Entity Beans	NO	NO
Java Persistence 2.0	YES	YES
Local/No-Interface Client View	YES	YES
3.0 Remote Client View	NO	NO
2.x Remote Home/Component	NO	NO
JAX-WS Web Service Endpoint	NO	NO
JAX-RPC Web Service Endpoint	NO	NO
EJB 3.0 Timer Service	NO	YES
Asynchronous session bean invocations	NO	YES
Interceptors	YES	YES
RMI-IIOP Interoperability	NO	NO
Container Managed Transactions	YES	YES
Bean Managed Transactions	YES	YES
Declerative Security	YES	YES
Programmatic Security	YES	YES
Embeddable API	YES	YES

In Siwpas, you can also use EJB Beans as Context and Dependency Injection (CDI) managed beans. You can inject EJB beans into other CDI beans and vice versa. See Java EE Technologies, CDI section to get more information.

In Siwpas, you can also use CDI based interceptors on EJB Beans. See Java EE Technologies, CDI section to get more information.

6.3. Siwpas EJB Lite Server (ELS) Configuration

There is a configuration file “openejb.xml” to configure Siwpas ELS. Configuration file is located in “$SIWPAS_HOME/conf/openejb.xml”.

Description	Location
Siwpas ELS Configuration File Location	$SIWPAS_HOME/conf/openejb.xml

In a default Siwpas distribution, “openejb.xml” file contains minimal configuration settings.

Default Configuration Settings,

· Containers Configuration : Configuration settings for “STATELESS, STATEFUL, SINGLETON and MANAGED” bean containers.

· DataSources Configuration : Describes default datasources based on HSQLDB.

In section 6.3.1 Detailed Configuration Parameters section, all configuration parameters and their descriptions are explained.

6.3.1. Detailed Configuration Parameters

“openejb.xml” file contains several different sections to override default configuration parameters of the Siwpas ELS. Each section configuration is specified by main XML elements (a.k.a Services).

Internally, Siwpas uses default configuration file for configuring its services. “openejb.xml” file is used for overriding these default configuration settings. You can override default configuration parameters via providing your own services.

Default openejb.xml in ${SIWPAS_HOME}/openejb.xml does not override all configuration settings of Siwpas ELS. For example, it does not contain “Default Transaction Manager” settings. If you wish to override “Default Transaction Manager”, you have to add transaction manager configuration into the openejb.xml file. This is the same for other default configurations that are not listed in openejb.xml file.

There are different XML elements (service) that you can update default configuration section or add new configuration section from scratch. These XML main elements are,

· “<Container>” : Used for configuring the Siwpas ELS bean containers, i.e “Stateless, Stateful, Singleton and Managed”.

· “<Resource>”: Used for configuring datasources (javax.sql.DataSource) and mail sessions (javax.mail.Session).

· “<ProxyFactory>” : Used for configuring proxy factories. There is no need to override default settings.

· “<SecurityService>” : Used for configuring security service. There is no need to override default settings. If you wish to implement your own SecurityService, see Section 8, Siwpas Security.

· “<TransactionManager>”: Used for configuring transaction manager. Generally there is no need to override default settings if you do not use transaction recovery in your application. If you wish to use Transaction Recovery and 2P-Commit (2 phase commit), you have to update configuration. See <TransactionManager> Service Section.

ProxyFactory, SecurityService and TransactionManager services are singleton services. If you do not add them into the openejb.xml configuration file, default instances are used. If you wish to override default configuration parameters of provided instances, you have to add them into the openejb.xml file.

6.3.2. <Container> Service Configuration

There are three types of container that you can override settings. These are,

· Stateless Container : <Container id="My Stateless Container" type="STATELESS">

· Stateful Container : <Container id="My Stateful Container" type="STATEFUL">

· Singleton Container: <Container id="My Singleton Container" type="SINGLETON">

There is no need to configure Managed Bean Container. Managed bean container is a special container that is used for providing Managed Beans that are defined in “Managed Beans 1.0 Specification”. You can get Managed Bean specification from,

Description	URL
Managed Bean Specification	http://jcp.org/en/jsr/summary?id=316

Managed Beans Specification defines common contract for all beans that are managed by the container. Generally, you will not use these types of managed beans directly but you use JSF or CDI based managed beans that obey the rules of Managed Bean Specification.

To override default settings, add updated/new properties into body section of <Container> element in openejb.xml file.

Figure 23 : Override or Add New Property for Container Configuration

Stateless Container Configuration Properties:

Below table shows Stateless Container configuration properties and their default values,

Property Name	Default Value	Description
AccessTimeout	0 milliseconds	Specifies the time an invocation should wait for an instance of the pool to become available. After the timeout is reached, if an instance in the pool cannot be obtained, the method invocation will fail. Usable time units: nanoseconds, microsecons, milliseconds,seconds, minutes, hours, days. Or any combination such as "1 hour and 27 minutes and 10 seconds"
CallbackThreads	5	When sweeping the pool for expired instances a thread pool is used to process calling @PreDestroy on expired instances as well as creating new instances as might be required to fill the pool to the minimum after a Flush or MaxAge expiration. The CallbackThreads setting dictates the size of the thread pool and is shared by all beans deployed in the container.
CloseTimeout	5 minutes	PostConstruct methods are invoked on all instances in the pool when the bean is undeployed and its pool is closed. The CloseTimeout specifies the maximum time to wait for the pool to close and PostConstruct methods to be invoked. Usable time units: nanoseconds, microsecons, milliseconds, seconds, minutes, hours, days. Or any combination such as "1 hour and 27 minutes and 10 seconds"
GarbageCollection	true	Allows Garbage Collection to be used as a mechanism for shrinking the pool. When set to true all instances in the pool, excluding the minimum, are eligible for garbage collection by the virtual machine as per the rules of java.lang.ref.SoftReference and can be claimed by the JVM to free memory. Instances garbage collected will have their @PreDestroy methods called during finalization.
IdleTimeout	0 minutes	Specifies the maximum time that an instance should be allowed to sit idly in the pool without use before it should be retired and removed. Usable time units: nanoseconds, microsecons, milliseconds, seconds, minutes, hours, days. Or any combination such as "1 hour and 27 minutes and 10 seconds"
MaxAge	0 hours	Specifies the maximum time that an instance should live before it should be retired and removed from use. This will happen gracefully. Useful for situations where bean instances are designed to hold potentially expensive resources such as memory or file handles and need to be periodically cleared out. Usable time units: nanoseconds, microsecons, milliseconds, seconds, minutes, hours, days. Or any combination such as "1 hour and 27 minutes and 10 seconds"
MaxAgeOffset	-1	Applies to MaxAge usage and would rarely be changed, but is a nice feature to understand. When the container first starts and the pool is filled to the minimum size, all those "minimum" instances will have the same creation time and therefore all expire at the same time dictated by the MaxAge setting. To protect against this sudden drop scenario and provide a more gradual expiration from the start the container will spread out the age of the instances that fill the pool to the minimum using an offset. The MaxAgeOffset is not the final value of the offset, but rather it is used in creating the offset and allows the spreading to push the initial ages into the future or into the past. The pool is filled at startup as follows: for (int i = 0; i < poolMin; i++) {long ageOffset = (maxAge / poolMin * i * maxAgeOffset) % maxAge;pool.add(new Bean(), ageOffset));} The default MaxAgeOffset is -1 which causes the initial instances in the pool to live a bit longer before expiring. As a concrete example, let's say the MinSize is 4 and the MaxAge is 100 years. The generated offsets for the four instances created at startup would be 0, -25, -50, -75. So the first instance would be "born" at age 0, die at 100, living 100 years. The second instance would be born at -25, die at 100, living a total of 125 years. The third would live 150 years. The fourth 175 years. A MaxAgeOffset of 1 would cause instances to be "born" older and therefore die sooner. Using the same example MinSize of 4 and MaxAge of 100 years, the life spans of these initial four instances would be 100, 75, 50, and 25 years respectively. A MaxAgeOffset of 0 will cause no "spreading" of the age of the first instances used to fill the pool to the minimum and these instances will of course reach their MaxAge at the same time. It is possible to set to decimal values such as -0.5, 0.5, -1.2, or 1.2.
MaxSize	10	Specifies the size of the bean pools for this stateless SessionBean container. If StrictPooling is not used, instances will still be created beyond this number if there is demand, but they will not be returned to the pool and instead will be immediately destroyed.
MinSize	0	Specifies the minimum number of bean instances that should be in the pool for each bean. Pools are prefilled to the minimum on startup. Note this will create start order dependencies between other beans that also eagerly start, such as other @Stateless beans with a minimum or @Singleton beans using @Startup. The @DependsOn annotation can be used to appropriately influence start order. The minimum pool size is rigidly maintained. Instances in the minimum side of the pool are not eligible for IdleTimeout or GarbageCollection, but are subject to MaxAge and flushing. If the pool is flushed it is immediately refilled to the minimum size with MaxAgeOffset applied. If an instance from the minimum side of the pool reaches its MaxAge, it is also immediately replaced. Replacement is done in a background queue using the number of threads specified by CallbackThreads
ReplaceAged	True	When ReplaceAged is enabled, any instances in the pool that expire due to reaching their MaxAge will be replaced immediately so that the pool will remain at its current size. Replacement is done in a background queue so that incoming threads will not have to wait for instance creation. The aim of his option is to prevent user requests from paying the instance creation cost as MaxAge is enforced, potentially while under heavy load at peak hours. Instances from the minimum side of the pool are always replaced when they reach their MaxAge, this setting dictates the treatment of non-minimum instances.
ReplaceFlushed	False	When ReplaceFlushed is enabled, any instances in the pool that are flushed will be replaced immediately so that the pool will remain at its current size. Replacement is done in a background queue so that incoming threads will not have to wait for instance creation. The aim of his option is to prevent user requests from paying the instance creation cost if a flush performed while under heavy load at peak hours. Instances from the minimum side of the pool are always replaced when they are flushed, this setting dictates the treatment of non-minimum instances. A bean may flush its pool by casting the SessionContext to Flushable and calling flush(). See SweepInterval for details on how flush is performed.
StrictPooling	True	StrictPooling tells the container what to do when the pool reaches it's maximum size and there are incoming requests that need instances. With strict pooling, requests will have to wait for instances to become available. The pool size will never grow beyond the the set MaxSize value. The maximum amount of time a request should wait is specified via the AccessTimeout setting. Without strict pooling, the container will create temporary instances to meet demand. The instances will last for just one method invocation and then are removed. Setting StrictPooling to false and MaxSize to 0 will result in no pooling. Instead instances will be created on demand and live for exactly one method call before being removed.
SweepInterval	5 minutes	The frequency in which the container will sweep the pool and evict expired instances. Eviction is how the IdleTimeout, MaxAge, and pool "flush" functionality is enforced. Higher intervals are better. Instances in use are excluded from sweeping. Should an instance expire while in use it will be evicted immediately upon return to the pool. Effectively MaxAge and flushes will be enforced as a part of normal activity or sweeping, while IdleTimeout is only enforcable via sweeping. This makes aggressive sweeping less important for a pool under moderate load. Usable time units: nanoseconds, microsecons, milliseconds, seconds, minutes, hours, days. Or any combination such as "1 hour and 27 minutes and 10 seconds"

Stateful Container Configuration Properties:

Below table shows Stateful Container configuration properties and their default values,

Property Name	Default Value	Description
AccessTimeout	0 milliseconds	Specifies the maximum time an invocation could wait for the stateful bean instance to become available before giving up. After the timeout is reached a javax.ejb.ConcurrentAccessTimeoutException will be thrown. Usable time units: nanoseconds, microsecons, milliseconds, seconds, minutes, hours, days. Or any combination such as "1 hour and 27 minutes and 10 seconds"
BulkPassivate	100	Property name that specifies the number of instances to passivate at one time when doing bulk passivation.
Cache	org.apache.openejb.core.stateful.SimpleCache	The cache is responsible for managing stateful bean instances. The cache can page instances to disk as memory is filled and can destroy abandoned instances. A different cache implementation can be used by setting this property to the fully qualified class name of the Cache implementation.
Capacity	1000	Specifies the size of the bean pools for this stateful SessionBean container.
Passivator	org.apache.openejb.core.stateful.SimplePassivater	The passivator is responsible for writing beans to disk at passivation time. Different passivators can be used by setting this property to the fully qualified class name of the PassivationStrategy implementation. The passivator is not responsible for invoking any callbacks or other processing, its only responsibly is to write the bean state to disk. Known implementations: * org.apache.openejb.core.stateful.RAFPassivater * org.apache.openejb.core.stateful.SimplePassivater
TimeOut	20	Specifies the time to wait between invocations. This value is measured in minutes. A value of 5 would result in a time-out of 5 minutes between invocations. A value of zero would mean no timeout

Singleton Container Configuration Properties:

Below table shows Singleton Container configuration properties and their default values,

Property Name

Default Value

Description

AccessTimeout

30 seconds

Specifies the maximum time an invocation could wait for the singleton bean instance to become available before giving up.

After the timeout is reached a javax.ejb.ConcurrentAccessTimeoutException will be thrown.

Usable time units: nanoseconds, microsecons, milliseconds, seconds, minutes, hours, days. Or any combination such as "1 hour and 27 minutes and 10 seconds"

6.3.3. <Resource> Service Configuration

There are two types of resources can be configured,

· DataSource

· Mail Session

To override default settings, add updated/new properties into body section of <Resource> element in openejb.xml file.

Figure 23 : Override or Add New Property for Resource Configuration

DataSource Configuration Properties:

Below table shows DataSource configuration properties and their default values,

Property Name	Default Value	Description
JtaManaged	True	Determines wether or not this data source should be JTA managed or user managed. If set to 'true' it will automatically be enrolled in any ongoing transactions. Calling begin/commit/rollback or setAutoCommit on the datasource or connection will not be allowed. If you need to perform these functions yourself, set JtaManaged to 'false' In terms of JPA persistence.xml: "JtaManaged=true" can be used as a 'jta-data-source' "JtaManaged=false" can be used as a 'non-jta-data-source'
JdbcDriver	org.hsqldb.jdbcDriver	Driver class name
JdbcUrl	jdbc:hsqldb:file:data/hsqldb/hsqldb	Url for creating connections
UserName	sa	Default user name
Password	“”	Default password
PasswordCipher	PlainText	The password codec to be used to retrieve the plain text password from a ciphered value. The default is no codec . In other words, it means password is not ciphered. There are two options · PlainText : PlainTextPasswordCipher class is an PasswordCipher implementation that does not use any encryption/decryption algorithm at all. · Static3DES : .StaticDESPasswordCipher class is an PasswordCipher implementation that uses a Triple-DES encryption algorithm. You can also implement your own chipher algorithm. Implement PasswordCipher interface, JAR it and add “META-INF/ org.apache.openejb.resource.jdbc.PasswordCipher/Your Cipher Name” into it. “Your Cipher Name” file contains the implementation class.
ConnectionProperties	Empty	The connection properties that will be sent to the JDBC driver when establishing new connections Format of the string must be [propertyName=property;]* NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here.
DefaultAutoCommit	true	The default auto-commit state of new connections
DefaultReadOnly	Not set	The default read-only state of new connections If not set then the setReadOnly method will not be called. (Some drivers don't support read only mode, ex: Informix)
DefaultTransactionIsolation	Not set	The default TransactionIsolation state of new connections If not set then the setTransactionIsolation method will not be called. The allowed values for this property are: · NONE · READ_COMMITTED · READ_UNCOMMITTED · REPEATABLE_READ · SERIALIZABLE Note: Most JDBC drivers do not support all isolation levels
InitialSize	0	The initial number of connections that are created when the pool is started
MaxActive	20	The maximum number of active connections that can be allocated from this pool at the same time, or a negative number for no limit.
MaxIdle	20	The maximum number of connections that can remain idle in the pool, without extra ones being released, or a negative number for no limit.
MinIdle	0	The minimum number of connections that can remain idle in the pool, without extra ones being created, or zero to create none.
MaxWait	-1	The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely.
ValidationQuery	Empty	The SQL query that will be used to validate connections from this pool before returning them to the caller. If specified, this query MUST be an SQL SELECT statement that returns at least one row.
TestOnBorrow	true	If true connections will be validated before being returned from the pool. If the validation fails, the connection is destroyed, and a new conection will be retrieved from the pool (and validated). NOTE - for a true value to have any effect, the ValidationQuery parameter must be set.
TestOnReturn	true	If true connections will be validated before being returned to the pool. If the validation fails, the connection is destroyed instead of being returned to the pool. NOTE - for a true value to have any effect, the ValidationQuery parameter must be set.
TestWhileIdle	false	If true connections will be validated by the idle connection evictor (if any). If the validation fails, the connection is destroyed and removed from the pool NOTE - for a true value to have any effect, the timeBetweenEvictionRunsMillis property must be a positive number and the ValidationQuery parameter must be set.
TimeBetweenEvictionRunsMillis	-1	The number of milliseconds to sleep between runs of the idle connection evictor thread. When set to a negative number, no idle connection evictor thread will be run.
NumTestsPerEvictionRun	3	The number of connectionss to examine during each run of the idle connection evictor thread (if any).
MinEvictableIdleTimeMillis	1800000	The minimum amount of time in ms a connection may sit idle in the pool before it is eligable for eviction by the idle connection evictor (if any).
PoolPreparedStatements	false	If true, a statement pool is created for each Connection and PreparedStatements created by one of the following methods are pooled: · public PreparedStatement prepareStatement(String sql); · public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency)
MaxOpenPreparedStatements	0	The maximum number of open statements that can be allocated from the statement pool at the same time, or zero for no limit. NOTE - Some drivers have limits on the number of open statements, so make sure there are some resources left for the other (non-prepared) statements.
AccessToUnderlyingConnectionAllowed	false	If true the raw physical connection to the database can be accessed using the following construct: Connection conn = ds.getConnection(); Connection rawConn = ((DelegatingConnection) conn).getInnermostDelegate(); ... conn.close() Default is false, because misbehaving programs can do harmfull things to the raw connection shuch as closing the raw connection or continuing to use the raw connection after it has been assigned to another logical connection. Be carefull and only use when you need direct access to driver specific extentions. NOTE: Do NOT close the underlying connection, only the original logical connection wrapper.

For example,

HSQLDB Example:

Figure 24 : HSQLDB Datasource Configuration

Derby Embedded Example:

Figure 25 : Derby Datasource Configuration

MySQL Example:

Figure 26 : MySQL Datasource Configuration

Oracle Example:

Figure 27 : Oracle Datasource Configuration

PostgreSQL Example:

Figure 28 : PostgreSQL Datasource Configuration

Instant DB Example:

Figure 29 : InstantDB Datasource Configuration

Mail Session Configuration Properties:

There are no mail session specific configuration parameters. If your mail provider has any specific properties, you can pass those properties into mail resource via XML.

In default configuration, Siwpas uses “org.apache.openejb.core.MailSessionFactory" service for creating mail sessions. In a default “openejb.xml” file, there is no configured Mail Session resource.

Example Mail Resource Configuration:

Figure 29 : Sample Mail Resource

6.3.4. <Transaction Manager> Service Configuration

There is no specific configuration setting for <TransactionManager> service in the “openejb.xml” file. Therefore, Siwpas ELS uses default transaction manager instance. To override default transaction manager instance, add <TransactionManager> section into the “openejb.xml” file and set its configuration properties.

Siwpas ELS uses Apache Geronimo Transaction Manager implementation. Geronimo Transaction Manager uses HOWL (High-speed ObjectWeb Logger) to log transactions.

You can get more detailed information from the following pages about Apache Geronimo and HOWL.

Description	URL
Apache Geronimo	http://geronimo.apache.org
HOWL	http://howl.ow2.org/

Transaction Manager Configuration Properties:

Below table shows Transaction Manager configuration properties and their default values,

Property Name	Default Value	Description
defaultTransactionTimeoutSeconds	600	Transaction time out in seconds. defaultTransactionTimeoutSeconds must be positive
TxRecovery	false	Whether or not Transactions will be recovered. When this flag is true, transactions are logged and recovered.
bufferSizeKb	32	HOWL Configuration Option. The size of buffers specified as a number of 1K blocks. For example : 4 à 4096 (4*1024) bytes large
checksumEnabled	true	HOWL Configuration Option. The checksumOption to set.
adler32Checksum	true	HOWL Configuration Option. The the adler32Checksum option to set.
flushSleepTimeMilliseconds	50	HOWL Configuration Option. The amount of time (specified in milli-seconds) the FlushManager should sleep.
logFileDir	txlog	HOWL Configuration Option. Log file directory.
logFileExt	log	HOWL Configuration Option. Log file extension.
logFileName	howl	HOWL Configuration Option. Log file name.
maxBlocksPerFile	-1	HOWL Configuration Option. The maxBlocksPerFile to set.
maxBuffers	0	HOWL Configuration Option. The maxBuffers to set.
maxLogFiles	2	HOWL Configuration Option. The maxLogFiles to set.
minBuffers	4	HOWL Configuration Option. The minBuffers to set.
threadsWaitingForceThreshold	-1	HOWL Configuration Option. The threadsWaitingForceThreshold to set.

In current setting of Siwpas ELS, transaction recovery is not enabled. To enable transaction recovery, you have to add <TransactionManager> service with “TxRecovery true” property into “$SIWPAS_HOME/conf/openejb.xml” file.

Example TransactionManager Service Configuration:

This configuration enables transaction recovery.

Figure 30 : Enable of Transaction Recovery

About : Auto Deployments Directory (<Deployments> Elements)

Siwpas ELS does not support automatic deployment of modules that are specified in openejb.xml file via “<Deployments>” XML element. Siwpas uses Apache Tomcat based deployments.

To get ORB (omg.omg.CORBA.ORB) and Mail Session (javax.mail.Session) from Siwpas ELS, you have to define these resources in openejb.xml configuration file.

Figure 31 : Enable of ORB and Mail Sessions

6.4. Siwpas ELS System Properties

There are system properties using to configure some aspects of the Siwpas ELS. This section will give these properties and their descriptions.

Siwpas ELS configurable system properties are given in the following table. You can override these properties with JVM -Dproperty_name or adding related property into the “${SIWPAS_HOME}/conf/openejb.properties.”

Property Name	Default Value	Description
openejb.conf.file OR openejb.configuration	SIWPAS_HOME/conf/openejb.xml	OpenEJB configuration file.
openejb.validation.skip	false	Enable validation of deployments. If true, deployments will be validated. Little performance decrease.
openejb.descriptors.output	false	If true, will writedeployments “openejb-cmp-generated-orm-”,”openejb-jar-xml” and “ejb-jar-xml-” to temp file location.
openejb.nobanner	false	Write information about server
openejb.home	SIWPAS_HOME/	OpenEJB home. Generally no need to override.
openejb.base	SIWPAS_BASE/	OpenEJB base. Generally no need to override.
openejb.logger.external	false	Logging is configured externally.
openejb.log.factory	Log4jLogStreamFactory	Implementation of org.apache.openejb.util. LogStreamFactory interface.
openejb.org.quartz.threadPool.class	org.apache.openejb.core.timer. DefaultTimerThreadPoolAdapter	Quartz thread pool adapter class. Implementation of org.quartz.spi.ThreadPool
openejb.authentication.realmName	Not Set	In embeddable usage, login to LocalInitialContext via Login(realmname, username,password). Generally not needed.
openejb.strict.interface.declaration	false	Anything declared as both <business-local> and <business-remote> is invalid in strict mode. Also looking annotations and interfaces on inheritance hierachy.
openejb.altdd.prefix	Not Set	Alternate prefix for descriptors. “,” seperated values. For example : "openejb.altdd.prefix", "footest, test" META-INF/footest.ejb-jar.xml META-INF/test.env-entry.properties Generally used in tests. Syntax of prefix with Java Code: if(!prefix.matches(".[.-]$"))) prefix += "."*
openejb.deployments.classpath	false	Deploys modules from server classpath.
openejb.deployments.classpath.include	“”	If deployments classpath true, this reg.expression specificed inclusion pattern.
openejb.deployments.classpath.exclude	/*	If deployments classpath true, this reg.expression specificed exclusion pattern.
openejb.deployments.classpath.filter.descriptors	false	Above include/exclude settings are used when no ejb-jar.xml is found in the module. If you wish to filter any module with ejb-jar.xml, set this property to true.
openejb.deployments.classpath.filter.systemapps	true	Filters known jars from scanning. (for example: openejb-api.jar)
openejb.annotations.deployer.skiplibs	See Siwpas conf/openejb.properties file	Comma seperated libraries for skipping annotations on them.
openejb.deploymentId.format
openejb.validation.output.level	MEDIUM	Comma seperated “TERSE,MEDIUM and VERBOSE” enums.
openejb.deployments.classpath.require.descriptor	Not Set	If set to EJB, ejb-jar.xml descriptors are required for deployment modules. If you do not wish to use non-descriptors (not have ejb-jar.xml) modules, then set this property EJB string .
openejb.jndiname.format	{deploymentId}{interfaceType.annotationName}	Jndi name format for binding EJB beans.
openejb.jndiname.failoncollision	True	When collision on JNDI name, continue to deployment or not. When set to false, continue to deployment and logs error.
openejb.ejbmodule.deployer.skipmodules	ROOT,console,console-doc	Skips EJB deployments for given context paths.

Other system properties of OpenEJB are not supported in Siwpas ELS. Setting other properties of OpenEJB in openejb.properties file can result in an undefined behavious. If you want to ask any other OpenEJB property, please contact us via forums or customer support pages.

6.5. Siwpas ELS Logging System

Siwpas ELS uses “Apache Log4j” as a base logging system. Logging configuration is located in “$SIWPAS_HOME/conf/log4j.properties” file.

Below figure is a part of this configuration file related with OpenEJB logs.

Figure 32 : OpenEJB Logging Configuration

You can also use this configuration file for your own applications log4j properties.

6.6. Deployment of EJBs into Web Modules (a.k.a Collapsed EAR)

To use EJB beans in web modules (WAR archives), there is nothing to do special. Just place your EJB beans into your web module and deploy it into the container.

If your module does not contain “ejb-jar.xml” descriptor in “WEB-INF” folder of the WAR archive, deployment of EJB beans depends the setting of “openejb.deployments.classpath.require.descriptor” system property. See below table to see different settings.

WEB-INF/ejb-jar.xml	Descriptor System Property	Result
YES	Not important	Deploy
NO	YES	Not Deploy
NO	NO	Deploy

Below figure is a snapshot of sample deployment directory archive in an Eclipse development environment

Figure 33 : Sample Deployment Content

With WEB-INF content,

Figure 34 : Sample Deployment Content WEB-INF Directory

This is a classical Web Application Archive (WAR) with EJB Beans.

6.6.1. Directory Structure of Collapsed EARs

Collapsed EARs are contains the following file and directories,

· WEB-INF/ : Contains “lib”,”classes”,”ejb-jar.xml”, “openejb-jar.xml”, “web.xml” files.

· WEB-INF/classes : Contains applications Java classes and other resources.

· WEB-INF/lib : Contains application JAR files etc.

· META-INF : Contains Tomcat specific “context.xml” file.

Deployment:

Drop your archive into the auto deployment folder of Siwpas, (in a default configuration, it is ${SIWPAS_HOME}/webapps. You can add/update it from ${SIWPAS_HOME}/conf/server.xml. To get further information, see Siwpas Web Server section.)

Only the “WEB-INF/ejb-jar.xml” file is used for configuring EJB Beans. Other descriptors from classpath libraries are not used.

7. Java EE Technologies Used in Siwpas

As explained in Section 4, Siwpas Architecture, Siwpas application server contains the following core Java EE techonlogies,

· JSP & Servlet,

· Java Server Faces,

· Enterprise Java Beans,

· Context and Dependency Injection,

· Java Persistence,

· Validation.

In this section, following ASF Java EE Projects that provide runtime platform for the above techonlogies are explained.

· Apache Bean Validation,

· Apache MyFaces,

· Apache OpenJPA,

· Apache OpenWebBeans.

7.1. Apache Bean Validation Project (BVAL)

The goal of the Bean Validation project is to deliver an implementation of the Bean Validation Specfication (JSR303), which is TCK compliant and works on Java SE 5 or later. The initial codebase for the project was donated to the ASF by a SGA from Agimatec GmbH and uses the ASL 2.0 license.

Description	Location
Bean Validation Specification	http://jcp.org/en/jsr/summary?id=303

You can get BVAL documentation from BVAL Web Site,

Description	Location
BVAL Documentation	http://incubator.apache.org/bval/cwiki/documentation.html

7.1.1. Injection of Validator and ValidatorFactory Instances

You can inject and use “javax.validation.Validator” and “javax.validation.ValidatorFactory” instances into your injectable classes.

For example, below sample shows how to inject Validator into EJB Beans instance via @Resource annotation.

Figure 35 : Injection of Validator instance

You can also inject ValidatorFactory and Validator instances into the servlets via @Resource annotation.

Figure 36 : Injection of ValidatorFactory into Servlet

7.1.2. More Information

For getting more information, visit the following links.

Description	Location
Reference Impl. Guide	http://docs.jboss.org/hibernate/stable/validator/reference/en/html/
API & Doc	http://docs.jboss.org/hibernate/beanvalidation/spec/1.0/api/

7.2. Apache MyFaces Project (MyFaces)

MyFaces is a family of projects related to the JavaServer Faces (JSF) specification published as part of the Java Community Process. The "core" project is an implementation of that specification. Other MyFaces projects implement related specifications (eg the Portlet Bridge), or add features to any JSF implementation (not just the Myfaces Core).

Siwpas includes MyFaces Core project, i.e implementation of the Java Server Faces 2 (JSF 2) specification.

Description	Location
JSF Specification	http://jcp.org/en/jsr/summary?id=314

You can get documentation from,

Description	Location
MyFaces Wiki	http://wiki.apache.org/myfaces/
Getting Started	http://myfaces.apache.org/gettingstarted.html

Nothing requires to use MyFaces in your web applications. You can write JSF enabled web applications and deploy into the Siwpas.

Besides core JSF functionality, Siwpas also provides following features,

· Using CDI Beans as JSF Beans, (and use CDI based injection)

· Inject EJB components into JSF Beans,

· Inject @PersistenceContext (i.e injection of JPA javax.persistence.EntityManager),

· Inject @PersistenceUnit (i.e injection of JPA javax.persistence.EntityManagerFaactory),

· Inject following resources via @Resource annotation,

o CDI Bean Manager, (javax.enterprise.inject.spi.BeanManager),

o JTA Transaction Manager, (javax.transaction.TransactionManager),

o JTA User Transaction, (javax.transaction.UserTransaction),

o JTA Transaction Sync. Registry, (javax.transaction.TransactionSynchronizationRegistry),

o ORB, (org.omg.CORBA.ORB),

o Validator, (javax.validation.Validator),

o Validator Factory, (javax.validation.ValidatorFactory)

o Mail Sessions, (javax.mail.Session),

o DataSources, (local and JTA based javax.sql.DataSource).

For CDI usage, see Apache OpenWebBeans section.

Example JSF Injection:

JSF Bean:

Figure 36 : Sample JSF Bean

With <h:commandButton> action print,

Figure 37 : Sample JSF Bean Print Method

Sample Page to call print method,

Figure 38 : Sample JSF Page to Print Injections

When user clicks “Print Injections....”, injections of instances are printed,

Figure 39 : Print of Injections

You can also inject those resources into the Servlets, Filters, CDI Beans and JSP Tag Classes.

7.2.1. More Information

For getting more information about JSF and MyFaces, visit MyFaces main page,

Description	Location
MyFaces Home	http://myfaces.apache.org/

7.3. Apache OpenJPA Project (OpenJPA)

Apache OpenJPA is a Java persistence project at The Apache Software Foundation that can be used as a stand-alone POJO persistence layer or integrated into any Java EE compliant container.

Description	Location
Java Persistence Specification	http://jcp.org/en/jsr/detail?id=317

You can get OpenJPA documentation from OpenJPA Web site,

Description	Location
OpenJPA Documentation	http://openjpa.apache.org/documentation.html

7.3.1. Injecting of EntityManager and EntityManagerFactory

You can inject JPA resources via

· @PersistenceContext annotation to inject “javax.persistence.EntityManager”,

· @PersistenceUnit annotation to inject “javax.persistence.EntityManagerFactory”.

Persistence Contexts/Units and DataSources;

Persistentence Context and Units are defined by its unit names. Unit names are corresponds to the Resource id’s in openejb.xml.

Example:

Figure 40 : persistence.xml

Injection of EntityManager and EntityManagerFactory instances,

Figure 41 : Injection with unit name

7.3.2. Useful Advices

7.3.2.1. Always set jta-data-source and non-jta-data-source

Always set the value of jta-data-source and non-jta-data-source in your persistence.xml file.

Regardless if targeting your EntityManager usage for transaction-type="RESOURCE_LOCAL" or transaction-type="TRANSACTION", it's very difficult to guarantee one or the other will be the only one needed. Often times the JPA Provider itself will require both internally to do various optimizations or other special features.

· The jta-data-source should always have it's OpenEJB-specific 'JtaManaged' property set to 'true' (this is the default),

· The non-jta-data-source should always have it's OpenEJB-specific 'JtaManaged' property set to 'false'.

7.3.2.2. Detach Issue

A warning for any new JPA user is by default all objects will detach at the end of a transaction. People typically discover this when the go to remove or update an object they fetched previously and get an exception like "You cannot perform operation delete on detached object".

There are some solutions to this problem,

· Use PersistenceContext.EXTENDED to increase lifecycle of persistence context (persistence context will be propogated with JTA transactions),

· Reattach detached object into persistence context using EntityManager.merge(instance) method.

7.3.3. Common Exceptions

7.3.3.1. Table not found in statement

Someone has to create the database structure for your persistent objects. If you add the openjpa.jdbc.SynchronizeMappings property as shown below OpenJPA will auto-create all your tables, all your primary keys and all foreign keys exactly to match your objects.

Figure 41 : Auto table creation

7.3.3.2. Extended Persistence Context with Resource Local Persistence Unit

If you want to use PersistenceContext.EXTENDED EntityManager in a JTA transaction, you must define persistence unit in persistence.xml as “JTA”. If you do not want to use “JTA” , then demarcate EJB method that uses EntityManager as “TransactionAttribute.NEVER” or “TransactionAttribute.NOT_SUPPORTED”.

Figure 42 : Using RESOURCE_LOCAL Entity Manager

7.3.4. More Information

For getting more information about JPA and OpenJPA, visit OpenJPA main page,

Description	Location
OpenJPA Home	http://openjpa.apache.org/

7.4. Apache OpenWebBeans Project (OpenWebBeans)

OpenWebBeans is an ASL-licensed implementation of the JSR-299 "Contexts and Dependency Injection for the Java (TM) EE platform" spezification. In addition to the implementation of the specification, the project provides a set of WebBeans components and integration plugins exposing functionality of other Apache Software Foundation projects.

Description	Location
CDI Specification	http://jcp.org/en/jsr/detail?id=299

Siwpas CDI is powered by the Apache OpenWebBeans project. Siwpas CDI has passed all the tests in CDI TCK and TCK compatible with version 1.0.4.CR2.

CDI TCK is licensed under ASF v2, therefore we are able to test Siwpas CDI using TCK. CDI TCK can be accessed from http://seamframework.org/Weld/Downloads.

7.4.1. Using CDI in Web Applications

To enable CDI in your web applications, put empty “beans.xml” file into “WEB-INF/” directory of your application.

Figure 43 : Location of “beans.xml” in deployment “WEB-INF/” directory.

After putting “beans.xml”, you can use CDI functionalites in your web projects,

· Use CDI Managed Beans as JSF Beans,

· Use EJB Beans as JSF Beans,

· Inject CDI Managed Beans into EJB Beans,

· Inject EJB Beans into CDI Managed Beans,

· Inject Java EE resources into CDI Managed Beans,

· Use CDI based interceptors,

· Use CDI decorators,

· Use CDI events,

· Use CDI Portable Extensions.

Here is a JSF Page that uses CDI Managed Bean,

Figure 44 : Sample JSF Page using CDI Managed Bean

Here is the CDI Managed Bean Class

Figure 45 : CDI Managed Bean

In Siwpas, you can also inject EJB Beans into CDI Managed Beans easily.

Figure 45 : CDI Managed Bean that Injects EJB Beans

Here is the EJB Bean that implements CDI API type ICalculator

Figure 45 : EJB Managed Bean

As you see, EJB Bean also injects CDI Bean “SimpleBean”.

In this section, we do not go into the details of the CDI Specification. OpenWebBeans specific configurations will be explained in this section.

7.4.2. OpenWebBeans Configuration Parameters

There are some configuration parameters that you can tweak to change default configuration of OpenWebBeans. These parameters are listed in the following table.

Actually, OpenWebBeans has more than these configuration parameters but it is not necessary to change unlisted parameters. Therefore, only configurable parameters have been listed in the following table.

Property Name	Default Value	Description
org.apache.webbeans.forceNoCheckedExceptions	False	Lifycycle methods like PostConstruct and PreDestroy must not define a checked Exception regarding to the spec. But this is often unnecessary restrictive so we allow to disable this check application wide.
org.apache.webbeans.conversation.Conversation.periodicDelay	150000	Conversation clean thread running period in miliseconds.
org.apache.webbeans.conversation.Conversation.timeoutInterval	1800000	Conversation timeout interval in miliseconds.
org.apache.webbeans.application.supportsConversation	True	Runtime supports conversations or not. If changed to false, conversations are not supported.
org.apache.webbeans.useBDABeansXMLScanner	False	If true, will enable decorators, interceptors and alternatives based on the beans.xml of the appropriate archive.
org.apache.webbeans.web.failover.issupportfailover	False	Application supports of failover
org.apache.webbeans.web.failover.issupportpassivation	False	Application supports of failover with passivation & actiovation of sessions

7.4.3. Inject Java EE resources into CDI Managed Beans

You can also inject Java EE Resources into your CDI Managed Beans.

Besides core CDI functionality, Siwpas also provides following features,

· Using CDI Beans as JSF Beans, (and use CDI based injection)

· Inject EJB components into CDI Beans,

· Inject CDI Beans into EJB,

· Inject @PersistenceContext (i.e injection of JPA javax.persistence.EntityManager),

· Inject @PersistenceUnit (i.e injection of JPA javax.persistence.EntityManagerFaactory),

· Inject following resources via @Resource annotation,

o CDI Bean Manager, (javax.enterprise.inject.spi.BeanManager),

o JTA Transaction Manager, (javax.transaction.TransactionManager),

o JTA User Transaction, (javax.transaction.UserTransaction),

o JTA Transaction Sync. Registry, (javax.transaction.TransactionSynchronizationRegistry),

o ORB, (org.omg.CORBA.ORB),

o Validator, (javax.validation.Validator),

o Validator Factory, (javax.validation.ValidatorFactory)

o Mail Sessions, (javax.mail.Session),

o DataSources, (local and JTA based javax.sql.DataSource).

You can also supports class type hierarchies. Therefore, if you inject in super class, you can get it from subclasses.

Here is an example,

Sub-Class,

Inherit also from super class,

Siwpas Wiki contains more samples. You can download samples from Siwpas page.

7.4.4. More Information

For getting more information about CDI and OpenWebBeans, visit following URLs

Description	Location
OpenWebBeans WIKI	https://cwiki.apache.org/confluence/display/OWB
CDI RI Page and Docs	http://seamframework.org/Weld/Documentation

8. Siwpas Security

Siwpas contains,

· Web Server, based on Apache Tomcat

· EJB Lite Server, based on Apache OpenEJB.

When client issues HTTP request, security policy is applied to the request according to the following logic,

· If there is no EJB bean in the flow, securit logic of the web server is applied,

· If there is EJB bean in the flow, after web server security logic, EJB server security logic is also applied to the request.

This flow is depicted in the following figure,

8.1. Siwpas Security Context

Siwpas Security Context is configured using Siwpas Security Realms (It is based on the Apache Tomcat Security Configuration). EJB Server uses this context while calling its EJB Beans.

8.1.1. Siwpas Security Realms

A Realm is a "database" of usernames and passwords that identify valid users of a web application (or set of web applications), plus an enumeration of the list of roles associated with each valid user.

You can think of roles as similar to groups in Unix-like operating systems, because access to specific web application resources is granted to all users possessing a particular role (rather than enumerating the list of associated usernames). A particular user can have any number of roles associated with their username.

Siwpas supports the following realms,

Realm Name	Description
JDBC Realm	Accesses authentication information stored in a relational database, accessed via a JDBC driver.
DataSource Realm	Accesses authentication information stored in a relational database, accessed via a named JNDI JDBC DataSource.
JNDI Realm	Accesses authentication information stored in an LDAP based directory server, accessed via a JNDI provider.
UserDatabase Realm	Accesses authentication information stored in an UserDatabase JNDI resource, which is typically backed by an XML document (conf/siwpas-users.xml).
Memory Realm	Accesses authentication information stored in an in-memory object collection, which is initialized from an XML document (conf/siwpas-users.xml).
JAAS Realm	Accesses authentication information through the Java Authentication & Authorization Service (JAAS) framework.

It is also possible to write your own Realm implementation, and integrate it with Siwpas. To do so, you need to:

· Implement org.apache.catalina.Realm,

· Place your compiled realm in $SIWPAS_HOME/lib,

· Configure your realm

You can get more detailed information about how to use and configure realms from Apache Tomcat Realm-Howto document.

Description	URL
Tomcat Realm Howto	http://tomcat.apache.org/tomcat-7.0-doc/realm-howto.html

8.1.2. Java Authorization Contract for Containers (JACC)

Siwpas EJB Lite Server uses Java Authorization Contract for Containers (JACC) to grant permissions to the EJB Bean callers. It is not necessary to replace the default JACC provider.

JACC PolicyConfiguration (org.apache.openejb.core.security.jacc. BasicPolicyConfiguration) holds roles to permissions map for EJB Beans. When web module that contains EJB Beans is deployed into the Siwpas, method permissions are built and added into the PolicyConfiguration.

When any EJB Bean’ method is executed, JACC finds caller permissions from its roles. Roles are taken from the Siwpas Security Context (setup by web server). If permisson exists for the return role, access is granted to the caller, otherwise access is denied.

If you want to changed the default JACC provider (org.apache.openejb.core.security.jacc. BasicJaccProvider) with your own custom JACC provider implementation,

· Extends class org.apache.openejb.core.security. JaccProvider,

· Set system property “org.apache.openejb.core.security.JaccProvider” into the “openejb.properties” in $SIWPAS_HOME/conf/ as

o org.apache.openejb.core.security.JaccProvider = YOUR JACC PROVIDER CLASS NAME

8.1.3. JAAS Login Modules

Siwpas provides three differents login module for using with JAAS Realm (See Siwpas Security Realms Section).

Description	Location
JAAS login.config File	$SIWPAS_HOME/conf/login.config

8.1.3.1. Properties Login Module

This login module uses Java properties files for “users” and “roles”.

Property Name	Description
Debug	Debug messages or not
UsersFile	Users file contains users and their passwords. Default location is $SIWPAS_BASE/conf/siwpas-users.properties
RolesFile	Roles file contains users’ roles. Default location is $SIWPAS_BASE/conf/siwpas-roles.properties
digest	MessageDigest.getInstance(digest); must not throw Exception
encoding	Only hex and base64 are supported

Digest and encoding are used for paasword comparison. In default configuration, there is no digest&encoding.

For example, define context.xml at META-INF with,

8.1.3.2. Memory Database Login Module

This login module uses UserDatabase resource for configuring “users” and “roles”.

Property Name	Description
Debug	Debug messages or not
Name	Unique name for UserDatabase
UsersFile	Users file contains users and their passwords. Default location is $SIWPAS_BASE/conf/siwpas-users.xml
RolesFile	Roles file contains users’ roles. Default location is $SIWPAS_BASE/conf/siwpas-roles.properties

For example, define context.xml at META-INF with,

8.1.3.3. SQL Login Module

This login module uses SQL database for getting users and roles.

Property Name		Description
dataSourceName		Datasource name defined in openejb.xml
userSelect		User selection query
roleSelect		Role selection query
digest		MessageDigest.getInstance(digest); must not throw Exception
encoding		Only hex and base64 are supported
jdbcURL		If dataSourceName not defined, defines database connection url string
jdbcUser		If dataSourceName not defined, defines database user
jdbcPassword		If dataSourceName not defined, defines database password
jdbcDriver		If dataSourceName not defined, defines database driver
	Related database driver library must be installed into Siwpas before using SQL Realm. (Putting related driver jar into the /lib directory of the server.).

For example, define context.xml at META-INF with,

8.2. Getting More Information

For getting more information about security, visit the following links,

Description	Location
Tomcat Security Manager	http://tomcat.apache.org/tomcat-7.0-doc/security-manager-howto.html
Tomcat Realms	http://tomcat.apache.org/tomcat-7.0-doc/realm-howto.html
OpenEJB Security	http://openejb.apache.org/3.0/security.html
Java Security	http://www.oracle.com/technetwork/java/javase/tech/index-jsp-136007.html

9. JNDI Naming On Siwpas

When application is deployed into the Siwpas, its JNDI tree is created. There are three different jndi contexts exist for the deployed web applications,

JNDI Context	Description
java:comp	Component level context.
java:module	Module level context.
java:app	Application level context.
java:global	Global level context.

Actually, for collapsed ears (web and ejb beans are contained in a single deployment), EJB Beans’ jndi contexts are merged with Web application jndi context. Therefore EJB Beans and Web Application shares the same jndi context entries.

In fact, EJB Beans jndi context and Web Application jndi context are two different contexts. But from the developer perspective, they are the same and contain the same jndi entries. For example, searching java:/comp/env/some_entry lookup will return the same jndi value!

For collapsed EARs, deployment module is also treated as single application deployment. (For Java EE Enterprise Deployments (EAR) into the full profile Java EE Servers, applications and modules are different artifacts. For example, one EAR application can contains several EJB and Web modules. This is not the case for Siwpas because Siwpas only deploys Web Modules that may contain EJB Beans).

9.1. Binding of Web Application Name

After you deploy web application into Siwpas, Siwpas create the following entries in the “module” and “application” contexts,

JNDI Name	Description
java:module/ModuleName	Name of the web application deployment.
java:app/AppName	Name of the web application deployment.

These jndi context entries contain the same value, web application deployment name. For example, when you deploy “sample_application.war” into the Siwpas, both of above jndi entries will have “sample_application” as their values.

9.2. Binding of EJB Beans

When you deploy collaped EAR that also contains EJB Beans, these beans are registered into the JNDI context of the web application according to the “openejb.jndiname.format” .

In a default configuration of the Siwpas, default jndi format value is “{deploymentId}{interfaceType.annotationName}”. Both deploymentId and interfaceType.annotationName are pre-defined variables. There are other pre-defined variables available which you could use to customize the JNDI name format.

9.2.1. OpenEJB JNDI Name Formatting

The openejb.jndiname.format property allows you to supply a template for the global JNDI names of all your EJBs. With it, you have complete control over the structure of the JNDI layout.

You can use the following pre-defined variables in jndi format,

Variable Name	Description
moduleId	Typically the name of the ejb-jar file or the <ejb-jar id=""> id value if specified
ejbType	STATEFUL, STATELESS,SINGLETON, MANAGED
ejbClass	for a class named org.acme.superfun.WidgetBean results in org.acme.superfun.WidgetBean
ejbClass.simpleName	for a class named org.acme.superfun.WidgetBean results in WidgetBean
ejbClass.packageName	for a class named org.acme.superfun.WidgetBean results in org.acme.superfun
ejbName	The ejb-name as specified in xml or via the 'name' attribute in an @Stateful, @Stateless, or @Singleton annotation or via the ‘name’ attribute in @ManagedBean.
deploymentId	The unique system id for the ejb. Typically the ejbName unless specified in the openejb-jar.xml or via changing the *openejb.deploymentId.format*
interfaceType.annotationName	Following the EJB 3 annotations @LocalHome and @Local. · *LocalHome* (EJB 2 EJBLocalHome) · *Local* (EJB 3 Business Local)
interfaceType	Same as *interfaceType.annotationName*
interfaceType.annotationNameLC	This is the same as *interfaceType.annotationName*, but all in lower case.
interfaceType.xmlName	Following the ejb-jar.xml descriptor elements <local-home>, <business-local>: · local-home (EJB 2 EJBLocalHome) · business-local (EJB 3 Business Local)
interfaceType.xmlNameCc	Camel-case version of interfaceType.xmlName: · LocalHome · BusinessLocal
interfaceClass	· (business) for a class named org.acme.superfun.WidgetLocal results in org.acme.superfun.WidgetLocal · (home) for a class named org.acme.superfun.WidgetLocalHome results in org.acme.superfun.WidgetLocalHome
interfaceClass.simpleName	· (business) for a class named org.acme.superfun.WidgetLocal results in WidgetLocal · (home) for a class named org.acme.superfun.WidgetLocalHome results in WidgetLocalHome
interfaceClass.packageName	for a class named org.acme.superfun.WidgetLocal results in org.acme.superfun

9.2.2. Configuring the EJB Bean’ JNDI names

It's possible to set the desired jndi name format for,

· The server level,

· An web module level,

· An ejb bean level ,

· An ejb bean's "local" interface (local/remote/local-home/home) level,

· An individual interface the ejb bean implements,

· An multiple jndi names.

More specific jndi name formats act as an override to any more general formats. The most specific format dictates the jndi name that will be used for any given interface of an ejb. It's possible to specify a general format for your server, override it at an ejb level and override that further for a specific interface of that ejb.

9.2.2.1. Configure Server Level

Open “openejb.properties” file in $SIWPAS_HOME/conf/openejb.properties and add the following entry,

· openejb.jndiname.format= YOUR JNDI FORMAT PATTERN

9.2.2.2. Configure Web Module Level

Add “openejb-jar.xml” into the deployment’ “WEB-INF/” directory.

Figure 47 : Sample openejb-jar.xml

9.2.2.3. Specific EJB Bean Level

Add “openejb-jar.xml” into the deployment’ “WEB-INF/” directory.

Figure 48 : Sample openejb-jar.xml

9.2.2.4. Specific EJB Bean’ Interface Type Level

Add “openejb-jar.xml” into the deployment’ “WEB-INF/” directory.

Figure 49 : Sample openejb-jar.xml

9.2.2.5. Specific EJB Bean’ Individual Interface Level

Add “openejb-jar.xml” into the deployment’ “WEB-INF/” directory.

Figure 49 : Sample openejb-jar.xml

9.2.2.6. Specific Multiple Jndi Name

Multiple <jndi> tags are allowed making it possible for you to be as specific as you need about the jndi name of each interface or each logical group of iterfaces (Local, Remote, LocalHome, RemoteHome).

Given an ejb, FooBean, with the following interfaces:

· business-local: org.superbiz.LocalOne,

· business-local: org.superbiz.LocalTwo

· local-home: org.superbiz.FooLocalHome

Figure 50 : Multiple jndi names

You are responsible for ensuring the names don't conflict.

9.2.2.7. Conservative Settings:

A very conservative setting such as "{deploymentId}/{interfaceClass}" would guarantee that each and every single interface is bound to JNDI.

Similarly conservative settings would be :

· {deploymentId}/{interfaceClass.simpleName}

· {moduleId}/{ejbName}/{interfaceClass}

· {ejbName}/{interfaceClass}

· {moduleId}/{ejbClass}/{interfaceClass}

· {ejbClass}/{interfaceClass}

· {ejbClass}/{interfaceClass.simpleName}

· {ejbClass.simpleName}/{interfaceClass.simpleName}

· {interfaceClass}/{ejbName}

Bordeline optimistic:

· {moduleId}/{interfaceClass}

· {interfaceClass}

The above two settings would work if you the interface wasn't shared by other beans.

9.2.2.8. Pragmatic Settings:

A more middle ground setting such as "{deploymentId}{interfaceType.annotationName}" would guarantee that at least one proxy of each interface type is bound to JNDI.

Similarly pragmatic settings would be:

· {moduleId}/{ejbClass}/{interfaceType.annotationName}

· {ejbClass}/{interfaceType.xmlName}

· {ejbClass.simpleName}/{interfaceType.xmlNameCc}

· {interfaceType}/{ejbName}

· {interfaceType}/{ejbClass}

9.2.2.9. Optimistic settings

A very optimistic setting such as "{deploymentId}" would guarantee only one proxy for the bean will be bound to JNDI. This would be fine if you knew you only had one type of interface in your beans.

Similarly optimistic settings would be:

· {ejbName}

· {ejbClass}

· {ejbClass.simpleName}

· {moduleId}/{ejbClass.simpleName}

· {moduleId}/{ejbName}

9.2.2.10. Collisions of JNDI Names

OpenEJB will reject the app when it detects that it cannot bind the second interface. This strict behavior can be disabled by setting the openejb.jndiname.failoncollision system property to false. When this property is set to false, we will simply log an error that the second proxy cannot be bound to JNDI, tell you which ejb is using that name, and continue loading your app.

9.3. EJB Specification Based Global JNDI Names

EJB Specification 3 also defines portable global jndi names for EJB Beans. Siwpas also supports portable global jndi names.

When EJB Bean is deployed via WAR archive, following entries are added to deployment jndi contexts as follows ,

JNDI Name

java:global/“Module Name”+ “Bean Name”

java:global/“Module Name”+ “Bean Name” + “!”+”Interface Name”

java:app/“Module Name”+ “Bean Name”

java:app/“Module Name”+ “Bean Name” + “!”+”Interface Name”

java:module/”Bean Name”

java:module/”Bean Name” + “!”+”Interface Name”

For example following Local EJB Bean in calculator.war,

Figure 50 : Sample Local EJB Bean

produces the following jndi entries in deployment jndi global, app and module contexts.

· java:global/calculator/Calculator

· java:global/calculator/Calculator!ICalculator

· java:app/calculator/Calculator!ICalculator

· java:module/Calculator

· java:module/Calculator!ICalculator

Any injectable type component can injecy EJB Beans via above jndi names.

For example:

@EJB(lookup=” java:module/Calculator!ICalculator”) ICalculator calculator;

Will return a proxy instance to the EJB Bean.

9.4. Default Injectable Resources

Siwpas also injectes the following resources into the web application “java:comp/” context. Developers can lookup these resource from their jndi names.

JNDI Name	Description
java:comp/TransactionManager	javax.transaction.TransactionManager instance.
java:comp/UserTransaction	javax.transaction.UserTransaction instance.
java:comp/TransactionSynchronizationRegistry	javax.transaction.TransactionSynchronizationRegistry instance.
java:comp/ORB	org.omg.CORBA.ORB instance.
java:comp/ValidatorFactory	javax.validation.ValidatorFactory instance.
java:comp/Validator	Javax.validation.Validator instance.
java:comp/BeanManager	If the deployment is CDI enabled, javax.enterprise.inject.spi.BeanManager instance.

There are three ways to get above instances from injectable components,

· Using InitialContext.lookup() method,

· Using @Resource(lookup=”jndi_name_of_instance”) method,

· Using @Resource without jndi name.

Example:

· TransactionManager manager = new InitialContext().lookup(“TransactionManager”);

· @Resource(lookup=”java:comp/TransactionManager”) TransactionManager manager;

· @Resource TransactionManager manager;

All of the above injections point to the same “TransactionManager” instance.

10. Transactions on Siwpas

Siwpas uses Apache Geronimo based transaction manager . Geronimo based transaction manager uses HOWL (High speed ObjectWeb Logger) Logger for saving transaction logs. (For recoverable transaction managers).

In Siwpas, Geronimo transaction manager is used for managing specific XA Resources (XA capable relational databases).

10.1. Transaction Manager Overview

Applications can delegate transaction management to the server infrastructure through application managed “User Transactions” or for ejbs “Container Manager Transactions”. In a container managed transaction, transaction is demarcated by the server. Developers are not required to involve with beginning/committing/rollbacking the transaction. On the other hand, developers are fully control over transaction demarcation using “javax.transaction.UserTransaction” object.

The server uses a transaction manager to coordinate this application view of transaction boundaries with the resource manager view of work done on specific data stores within particular transactions. Siwpas uses a Geronimo based JTA TransactionManager implementation that uses HOWL.

10.1.1. Configuring the Transaction Manager Identity

In order for XA transactions to work properly, each Siwpas instance connecting to a resource manager such as an XA capable database needs to have a globally unique and permanent Id. The Id needs to be unique to avoid the same Xid being generated by several Siwpas instances, which would indicate to the resource manager that work done in completely unrelated transactions from different servers was actually part of the same transaction, and the Id needs to be permanent so that the recovery process can associate in-doubt transactions with the correct server.

In Siwpas (in Geronimo Transaction Manager) this id is a byte sequence configured in the XidFactory service in the transaction plugin. Do not change this while the server is running or while there are any in-doubt transactions anywhere in your system. This is the server identity as far as the xa system is concerned. For instance if a server becomes permanently unavailable due to hardware failure you can recover in-doubt transactions it is responsible for by setting up another server with the same apps and the dead server's TmId.

If you want to set another tmId, add “tmId ” property to TransactionManager service configuration in “openejb.xml” as,

Figure : Changing Transaction Manager Id

10.2. JTA and Non-JTA Managed DataSources

In Siwpas, transaction manager is used for coordinating the database resources (datasources) in JTA transactions. There are three type of DataSource that can be used in Siwpas

· JTA Managed DataSource (XAResource)

· JTA Managed DataSource with XA Recovery

· Non-JTA Managed DataSource (LocalXAResource)

Corresponding datasource classes are,

Type	Class Name
JTA Managed without Recovery	org.apache.openejb.resource.jdbc.BasicManagedDataSource
JTA Managed with Recovery	org.apache.openejb.resource.jdbc.ManagedDataSourceWithRecovery
Non-JTA Managed	org.apache.openejb.resource.jdbc.BasicDataSource

As explained in section Resource Service Section, datasources are defined in “$SIWPAS_HOME/conf/openejb.xml” configuration file.

10.3. Injection of Transactional Objects

You can inject the following transactional objects into your components,

· TransactionManager, (javax.transaction.TransationManager),

· UserTransaction, (javax.transaction.UserTransaction),

· TransactionSynchronizationRegistry(javax.transaction.TransactionSynhronizationRegistry)

You can use two different ways for injecting above resources,

· Via @Resource(lookup=”jndi_name_of_instance”)

· Via @Resource

Example for injecting UserTransaction instance,

@Resource UserTransaction userTransaction OR

@Resource(lookup=”java:comp/UserTransaction”) UserTransaction userTransaction;

10.4. Transaction Manager Configuration

See Transaction Manager Service section for how to configure transaction manager.

10.5. Using Transaction in EJB Beans, Basic Information

One of the many benefits of EJB, is that transactions within the EJB container are generally managed entirely automatically. Any EJB component will, by default, participate in that transaction.

10.5.1. Basic Rules

There are some basic default rules for using transactions in EJBs

· A transaction starts at the beginning of the first EJB method call, in a chain of calls that are participating in the given transaction,

· A transaction ends at the end of the first EJB method, in the same chain,

· If a bean that has started a transaction, uses another bean, that bean will automatically use the same transaction as the calling bean.

10.5.2. Transaction Attribute Configuration

You can configure your beans in a variety of ways. Generally speaking, a transaction is started when a method is called, but can be configured using @TransactionAttribute(value = TransactionAttributeType.X), where X is one of,

Transaction Attribute	Description
REQUIRED	The default, which is to start a transaction if one does not exist, but to use the existing one if it has already been started.
REQUIRES_NEW	The transaction is created on every call, and ends when the call is completed. Beans don't partake in transactions created by other parts of the system.
MANDATORY	A transaction must always exist prior to the call, and it will be used. It is an error otherwise
NOT_SUPPORTED	Component not included in the transaction
SUPPORTS	Transaction will be used if it exists, but will not be created if it does not exist
NEVER	If a transaction exists, it is an error to call the method

@TransactionAttribute applies to both methods and entire beans. You may set one type of transaction behaviour (as seen above) on the bean, and a different one on a specific method of that same bean, which overrides the one configured for the overall bean.

10.6. JPA Entity Managers in JTA Transactions

You can use container managed JPA Entity Managers in your EJB Beans. To use container managed JPA Entity Managers, persistence unit must be defined as “transaction-type=JTA”.

Example;

When you have JTA based persistence unit, you can inject Entity Managers into your EJB Beans Entity manager is automatically enlisted with current transaction. When transaction is committed/rolledback, entity manager is automatically committed/rolledback.

11. Siwpas Clustering Guide

Siwpas has following clustering features in addition to the Tomcat native clustering.

· Clustering of CDI Managed Beans,

· Clustering of EJB Stateful Beans.

11.1. CDI Bean Clustering

In a default configuration, clustering of the CDI beans are not enabled for web deployments. To enable CDI bean clustering, you have to add the following “openwebbeans.properties” file into the “META-INF/openwebbeans/openwebbeans.properties”.

To enable CDI clustering, add “openwebbeans.properties” file with the clustering configuration into the web application “META-INF/openwebbeans” classpath folder.

Content of the openwebbeans.properties:

configuration.ordinal=100

org.apache.webbeans.spi.FailOverService=org.apache.webbeans.web.failover.DefaultOwbFailOverService

org.apache.webbeans.web.failover.issupportfailover=true

org.apache.webbeans.web.failover.issupportpassivation=true

Passivation is used for passivating the CDI beans into the persistent store on server shutdown. Those beans are restored at the befining of server startup. Failing over is used for enabling CDI beans in another node in the cluster when active node is failed.

CDI Beans that are @SessionScoped or @ConversationScoped beans are passivation capable beans and automatically fail over to another node if current active node is failed. Their dependencies must obey the rules of CDI Specification Passivation Capable Dependencies.

11.2. EJB Stateful Bean Clustering

Siwpas 2.0.0 supports the clustering of the EJB stateful beans using the Apache Tribe communication framework.

In default Siwpas configuration, EJB Stateful Bean clustering is disabled. To enable EJB clustering, set “openejb.sfsb.cluster.enabled=false” to “true” in “conf/openejb.properties” file. Also, uncomment the “ClusterContainer” definition from “conf/openejb.xml”

EJB Stateful Beans Clustering in the Siwpas is implemented using the Apache Tribe Communication framework. Therefore, it is required that 2 Siwpas instances must be placed in a same cluster domain. You can enable the server clustering via uncommenting the cluster definition in the “conf/server.xml”.

For example, to use SimpleTCP Cluster, uncomment the following definition in “conf/server.xml”,

<Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/>.

To enable the EJB Stateful Bean Clustering, open “conf/openejb.prıoperties” and set “openejb.sfsb.cluster.enabled=false” to “true”. Moreover, open “conf/openejb.xml” file and uncomment the “ClusterContainer” container definition.

Cluster container has its own clustered cache. This cache is responsible for communicating with the other EJB Containers using Apache Tribe Communication framework.

11.3. Configuration Parameters

There are several configuration parameters that you can configure the EJB Clustering operations. Those parameter are located in the “conf/openejb.properties”.

Configuration Parameter	Description
openejb.sfsb.cluster.enabled	Clustering is enabled or nor, default cluster is not enabled
openejb.sfsb.cluster.propogateRemoveOnShutdown.enabled	Remove stateful beans on other nodes when current node is shut down. Default is false
openejb.sfsb.cluster.initialSessionTransfer.sendBlockSize	Initial state transfer block size, default is 1000 byte chunks
openejb.sfsb.cluster.initialSessionTransfer.sendBlockWaitTime	Initial state transfer chunk sending waiting time in miliseconds
openejb.sfsb.cluster.initialSessionTransfer.sendAll	Send initial state at single pass, default is true
openejb.sfsb.cluster.initialSessionTransfer.timeout	Initial state transfer timeout in miliseconds. Default is 10000

Example Code:

To enable EJB Bean Clustering, you have to define bean’s container is “ClusterContainer” using the @EjbDeployment annotation.

Stateful EJB Beans are automatically managed by the clustered container using @EjbDeployment(name=”ClusterContainer”) annotation. If the bean is not annotated with @EjbDeployment, clustering of this bean is not enabled.

IMPORTANT NOTE: For performance reasons, your EJB Stateful Bean can optionally implement “siwpas.mechsoft.com.tr.integration.cluster.container.SfsbPropogateControl” interface. This interface provides one method “public boolean propogateNecessary()”. Siwpas clustering framework calls this method to decide whether or not propogation is necessary.

EXAMPLE:

public class MyBean implements SfsbPropogateControl{

public boolean propogateNecessary(){

//Write your own control

}

12. Useful References

Here is the reference for getting more information about Siwpas, Java EE related technologies, projects, licenses, foundations and communities.

Siwpas References

Description	Location
MechSoft Home Page	http://www.mechsoft.com.tr
Siwpas Home Page	http://siwpas.mechsoft.com.tr
Siwpas User Forum	http://siwpas.mechsoft.com.tr/forum
Siwpas Bug Tracker	http://siwpas.mechsoft.com.tr/bugs
Siwpas Wiki	http://siwpas.mechsoft.com.tr/wiki
Siwpas Source	http://siwpas.mechsoft.com.tr/downloads
Siwpas Documents	http://siwpas.mechsoft.com.tr/docs
Siwpas Sales	http://siwpas.mechsoft.com.tr/sales

So share your experiences with us and let us know how we can make Siwpas even better.Please send your support requests to siwpas-support@mechsoft.com.tr with a detailed infromation.

Thanks for using Siwpas, Simple Web Profile Application Server!

Other References

Description	Location
Java Platform, Enterprise Edition (Java EE) Specification, v6	http://jcp.org/en/jsr/summary?id=316
LGPL License Home Page	http://www.gnu.org/copyleft/lesser.html
Apache Software Foundation	http://apache.org
Java Platform, Enterprise Edition 6 (Java EE 6) Web Profile Specification	http://jcp.org/en/jsr/summary?id=316
Common Annotations	http://jcp.org/en/jsr/detail?id=250
Apache OpenEJB	http://openejb.apache.org
Apache Tomcat	http://tomcat.apache.org
Apache MyFaces	http://myfaces.apache.org
Apache OpenWebBeans	http://openwebbeans.apache.org
Apache Bean Validation	http://incubator.apache.org/bval/cwiki/index.html
Apache OpenJPA	http://openjpa.apache.org
Apache Geronimo	http://geronimo.apache.org

13. Licenses

Here is the LGPL v3 License,

GNU LESSER GENERAL PUBLIC LICENSE

Version 3, 29 June 2007

Everyone is permitted to copy and distribute verbatim copies

of this license document, but changing it is not allowed.

This version of the GNU Lesser General Public License incorporates

the terms and conditions of version 3 of the GNU General Public

License, supplemented by the additional permissions listed below.

0. Additional Definitions.

As used herein, "this License" refers to version 3 of the GNU Lesser

General Public License, and the "GNU GPL" refers to version 3 of the GNU

General Public License.

"The Library" refers to a covered work governed by this License,

other than an Application or a Combined Work as defined below.

An "Application" is any work that makes use of an interface provided

by the Library, but which is not otherwise based on the Library.

Defining a subclass of a class defined by the Library is deemed a mode

of using an interface provided by the Library.

A "Combined Work" is a work produced by combining or linking an

Application with the Library. The particular version of the Library

with which the Combined Work was made is also called the "Linked

Version".

The "Minimal Corresponding Source" for a Combined Work means the

Corresponding Source for the Combined Work, excluding any source code

for portions of the Combined Work that, considered in isolation, are

based on the Application, and not on the Linked Version.

The "Corresponding Application Code" for a Combined Work means the

object code and/or source code for the Application, including any data

and utility programs needed for reproducing the Combined Work from the

Application, but excluding the System Libraries of the Combined Work.

1. Exception to Section 3 of the GNU GPL.

You may convey a covered work under sections 3 and 4 of this License

without being bound by section 3 of the GNU GPL.

2. Conveying Modified Versions.

If you modify a copy of the Library, and, in your modifications, a

facility refers to a function or data to be supplied by an Application

that uses the facility (other than as an argument passed when the

facility is invoked), then you may convey a copy of the modified

version:

a) under this License, provided that you make a good faith effort to

ensure that, in the event an Application does not supply the

function or data, the facility still operates, and performs

whatever part of its purpose remains meaningful, or

b) under the GNU GPL, with none of the additional permissions of

this License applicable to that copy.

3. Object Code Incorporating Material from Library Header Files.

The object code form of an Application may incorporate material from

a header file that is part of the Library. You may convey such object

code under terms of your choice, provided that, if the incorporated

material is not limited to numerical parameters, data structure

layouts and accessors, or small macros, inline functions and templates

(ten or fewer lines in length), you do both of the following:

a) Give prominent notice with each copy of the object code that the

Library is used in it and that the Library and its use are

covered by this License.

b) Accompany the object code with a copy of the GNU GPL and this license

document.

4. Combined Works.

You may convey a Combined Work under terms of your choice that,

taken together, effectively do not restrict modification of the

portions of the Library contained in the Combined Work and reverse

engineering for debugging such modifications, if you also do each of

the following:

a) Give prominent notice with each copy of the Combined Work that

the Library is used in it and that the Library and its use are

covered by this License.

b) Accompany the Combined Work with a copy of the GNU GPL and this license

document.

c) For a Combined Work that displays copyright notices during

execution, include the copyright notice for the Library among

these notices, as well as a reference directing the user to the

copies of the GNU GPL and this license document.

d) Do one of the following:

0) Convey the Minimal Corresponding Source under the terms of this

License, and the Corresponding Application Code in a form

suitable for, and under terms that permit, the user to

recombine or relink the Application with a modified version of

the Linked Version to produce a modified Combined Work, in the

manner specified by section 6 of the GNU GPL for conveying

Corresponding Source.

1) Use a suitable shared library mechanism for linking with the

Library. A suitable mechanism is one that (a) uses at run time

a copy of the Library already present on the user's computer

system, and (b) will operate properly with a modified version

of the Library that is interface-compatible with the Linked

Version.

e) Provide Installation Information, but only if you would otherwise

be required to provide such information under section 6 of the

GNU GPL, and only to the extent that such information is

necessary to install and execute a modified version of the

Combined Work produced by recombining or relinking the

Application with a modified version of the Linked Version. (If

you use option 4d0, the Installation Information must accompany

the Minimal Corresponding Source and Corresponding Application

Code. If you use option 4d1, you must provide the Installation

Information in the manner specified by section 6 of the GNU GPL

for conveying Corresponding Source.)

5. Combined Libraries.

You may place library facilities that are a work based on the

Library side by side in a single library together with other library

facilities that are not Applications and are not covered by this

License, and convey such a combined library under terms of your

choice, if you do both of the following:

a) Accompany the combined library with a copy of the same work based

on the Library, uncombined with any other library facilities,

conveyed under the terms of this License.

b) Give prominent notice with the combined library that part of it

is a work based on the Library, and explaining where to find the

accompanying uncombined form of the same work.

6. Revised Versions of the GNU Lesser General Public License.

The Free Software Foundation may publish revised and/or new versions

of the GNU Lesser General Public License from time to time. Such new

versions will be similar in spirit to the present version, but may

differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the

Library as you received it specifies that a certain numbered version

of the GNU Lesser General Public License "or any later version"

applies to it, you have the option of following the terms and

conditions either of that published version or of any later version

published by the Free Software Foundation. If the Library as you

received it does not specify a version number of the GNU Lesser

General Public License, you may choose any version of the GNU Lesser

General Public License ever published by the Free Software Foundation.

If the Library as you received it specifies that a proxy can decide

whether future versions of the GNU Lesser General Public License shall

apply, that proxy's public statement of acceptance of any version is

permanent authorization for you to choose that version for the

Library.

Here is the ASF v2 License,

  Apache License

                           Version 2.0, January 2004

                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,

      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by

      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all

      other entities that control, are controlled by, or are under common

      control with that entity. For the purposes of this definition,

      "control" means (i) the power, direct or indirect, to cause the

      direction or management of such entity, whether by contract or

      otherwise, or (ii) ownership of fifty percent (50%) or more of the

      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity

      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,

      including but not limited to software source code, documentation

      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical

      transformation or translation of a Source form, including but

      not limited to compiled object code, generated documentation,

      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or

      Object form, made available under the License, as indicated by a

      copyright notice that is included in or attached to the work

      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object

      form, that is based on (or derived from) the Work and for which the

      editorial revisions, annotations, elaborations, or other modifications

      represent, as a whole, an original work of authorship. For the purposes

      of this License, Derivative Works shall not include works that remain

      separable from, or merely link (or bind by name) to the interfaces of,

      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including

      the original version of the Work and any modifications or additions

      to that Work or Derivative Works thereof, that is intentionally

      submitted to Licensor for inclusion in the Work by the copyright owner

      or by an individual or Legal Entity authorized to submit on behalf of

      the copyright owner. For the purposes of this definition, "submitted"

      means any form of electronic, verbal, or written communication sent

      to the Licensor or its representatives, including but not limited to

      communication on electronic mailing lists, source code control systems,

      and issue tracking systems that are managed by, or on behalf of, the

      Licensor for the purpose of discussing and improving the Work, but

      excluding communication that is conspicuously marked or otherwise

      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity

      on behalf of whom a Contribution has been received by Licensor and

      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of

      this License, each Contributor hereby grants to You a perpetual,

      worldwide, non-exclusive, no-charge, royalty-free, irrevocable

      copyright license to reproduce, prepare Derivative Works of,

      publicly display, publicly perform, sublicense, and distribute the

      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of

      this License, each Contributor hereby grants to You a perpetual,

      worldwide, non-exclusive, no-charge, royalty-free, irrevocable

      (except as stated in this section) patent license to make, have made,

      use, offer to sell, sell, import, and otherwise transfer the Work,

      where such license applies only to those patent claims licensable

      by such Contributor that are necessarily infringed by their

      Contribution(s) alone or by combination of their Contribution(s)

      with the Work to which such Contribution(s) was submitted. If You

      institute patent litigation against any entity (including a

      cross-claim or counterclaim in a lawsuit) alleging that the Work

      or a Contribution incorporated within the Work constitutes direct

      or contributory patent infringement, then any patent licenses

      granted to You under this License for that Work shall terminate

      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the

      Work or Derivative Works thereof in any medium, with or without

      modifications, and in Source or Object form, provided that You

      meet the following conditions:

      (a) You must give any other recipients of the Work or

          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices

          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works

          that You distribute, all copyright, patent, trademark, and

          attribution notices from the Source form of the Work,

          excluding those notices that do not pertain to any part of

          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its

          distribution, then any Derivative Works that You distribute must

          include a readable copy of the attribution notices contained

          within such NOTICE file, excluding those notices that do not

          pertain to any part of the Derivative Works, in at least one

          of the following places: within a NOTICE text file distributed

          as part of the Derivative Works; within the Source form or

          documentation, if provided along with the Derivative Works; or,

          within a display generated by the Derivative Works, if and

          wherever such third-party notices normally appear. The contents

          of the NOTICE file are for informational purposes only and

          do not modify the License. You may add Your own attribution

          notices within Derivative Works that You distribute, alongside

          or as an addendum to the NOTICE text from the Work, provided

          that such additional attribution notices cannot be construed

          as modifying the License.

      You may add Your own copyright statement to Your modifications and

      may provide additional or different license terms and conditions

      for use, reproduction, or distribution of Your modifications, or

      for any such Derivative Works as a whole, provided Your use,

      reproduction, and distribution of the Work otherwise complies with

      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,

      any Contribution intentionally submitted for inclusion in the Work

      by You to the Licensor shall be under the terms and conditions of

      this License, without any additional terms or conditions.

      Notwithstanding the above, nothing herein shall supersede or modify

      the terms of any separate license agreement you may have executed

      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade

      names, trademarks, service marks, or product names of the Licensor,

      except as required for reasonable and customary use in describing the

      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or

      agreed to in writing, Licensor provides the Work (and each

      Contributor provides its Contributions) on an "AS IS" BASIS,

      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or

      implied, including, without limitation, any warranties or conditions

      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A

      PARTICULAR PURPOSE. You are solely responsible for determining the

      appropriateness of using or redistributing the Work and assume any

      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,

      whether in tort (including negligence), contract, or otherwise,

      unless required by applicable law (such as deliberate and grossly

      negligent acts) or agreed to in writing, shall any Contributor be

      liable to You for damages, including any direct, indirect, special,

      incidental, or consequential damages of any character arising as a

      result of this License or out of the use or inability to use the

      Work (including but not limited to damages for loss of goodwill,

      work stoppage, computer failure or malfunction, or any and all

      other commercial damages or losses), even if such Contributor

      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing

      the Work or Derivative Works thereof, You may choose to offer,

      and charge a fee for, acceptance of support, warranty, indemnity,

      or other liability obligations and/or rights consistent with this

      License. However, in accepting such obligations, You may act only

      on Your own behalf and on Your sole responsibility, not on behalf

      of any other Contributor, and only if You agree to indemnify,

      defend, and hold each Contributor harmless for any liability

      incurred by, or claims asserted against, such Contributor by reason

      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following

      boilerplate notice, with the fields enclosed by brackets "[]"

      replaced with your own identifying information. (Don't include

      the brackets!)  The text should be enclosed in the appropriate

      comment syntax for the file format. We also recommend that a

      file or class name and description of purpose be included on the

      same "printed page" as the copyright notice for easier

      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

   Licensed under the Apache License, Version 2.0 (the "License");

   you may not use this file except in compliance with the License.

   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software

   distributed under the License is distributed on an "AS IS" BASIS,

   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

   See the License for the specific language governing permissions and

   limitations under the License.

Here is the more information about above licenses

Description	Location
Apache License FAQ	http://www.apache.org/foundation/licence-FAQ.html
GPL & LGPL License FAQ	http://www.gnu.org/licenses/gpl-faq.html