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