MECHSOFT MECHANICAL AND SOFTWARE SOLUTIONS

Siwpas Administration Guide

 

MechSoft Software Group

01.01.2013

 

 

Siwpas administration guide provides detailed information about how to configure and use Siwpas.

 


 

1.      Forward. 5

1.1.       About This Guide. 5

1.2.       About OW2. 5

1.3.       About MechSoft Mechanical and Software Solutions. 6

About Mechanical Group. 6

About Software Group. 6

1.4.       Contact OW2. 6

1.5.       Contact MechSoft. 6

Legal Notices. 7

Thanks to OW2 Consortium.. 8

Thanks to Apache Software Foundation. 8

2.      Introduction. 9

2.1.       Terminology. 9

2.2.       About Siwpas. 9

2.3.       Why Siwpas, Why Another Server?. 10

2.4.       Siwpas License. 10

2.5.       Siwpas Professional Support. 10

2.6.       Web Profile Compliance. 11

2.6.1.         JSR-299 and JSR-303 TCKs. 11

2.7.       What is Web Profile?. 11

2.8.       Apache Software Foundation EE Projects. 12

2.9.       Useful Links. 13

3.      Getting Started. 14

3.1.       Installing Prerequisite Software. 14

3.2.       Download and Install the Siwpas Binary Distribution. 14

3.2.1.        Directory Structure. 14

3.2.2.        Siwpas Configuration Files. 15

3.2.3.        Advanced Configuration - Multiple Siwpas Instances. 16

3.3.       Start Up Siwpas. 16

3.4.       Shut Down Siwpas. 18

3.5.       Running Siwpas as Windows Service. 19

3.5.1.         Siwpas1 Service Application. 19

3.5.2.         Installing Siwpas Windows Service. 21

3.5.3.         Starting The Service. 22

3.5.4.         Removing Windows Service. 24

3.6.       Open Siwpas Administration Console. 24

3.7.       Section Summary. 24

4.      Siwpas Architecture. 25

4.1.       Siwpas Components. 25

5.      Siwpas Web Server. 27

5.1.       Logging File Content. 27

5.2.       Catalina System Properties File Content. 27

5.2.1.        Strict Servlet Compliance. 28

6.      Siwpas Enterprise Java Beans (EJB) Lite Server. 29

6.1.       What is EJB?. 29

6.2.       What is EJB Lite?. 29

6.3.       Siwpas EJB Lite Server (ELS) Configuration. 31

6.3.1.         Detailed Configuration Parameters. 31

6.3.2.         <Container>  Service Configuration. 32

6.3.3.         <Resource>  Service Configuration. 35

6.3.4.         <Transaction Manager> Service Configuration. 40

6.4.       Siwpas ELS System Properties. 42

6.5.       Siwpas ELS Logging System.. 43

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

6.6.1.         Directory Structure of Collapsed EARs. 45

7.      Java EE Technologies Used in Siwpas. 46

7.1.       Apache Bean Validation Project (BVAL). 46

7.1.1.         Injection of Validator and ValidatorFactory Instances. 46

7.1.2.         More Information. 47

7.2.       Apache MyFaces Project (MyFaces). 47

7.2.1.         More Information. 50

7.3.       Apache OpenJPA Project (OpenJPA). 50

7.3.1.        Injecting of EntityManager and EntityManagerFactory. 50

7.3.2.        Useful Advices. 51

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

7.3.2.2.          Detach Issue. 51

7.3.3.        Common Exceptions. 52

7.3.3.1.          Table not found in statement. 52

7.3.3.2.          Extended Persistence Context with Resource Local Persistence Unit. 52

7.3.4.        More Information. 52

7.4.       Apache OpenWebBeans Project (OpenWebBeans). 52

7.4.1.        Using CDI in Web Applications. 53

7.4.2.        OpenWebBeans Configuration Parameters. 55

7.4.3.        Inject Java EE resources into CDI Managed Beans. 55

7.4.4.        More Information. 56

8.      Siwpas Security. 57

8.1.       Siwpas Security Context. 57

8.1.1.        Siwpas Security Realms. 57

8.1.2.        Java Authorization Contract for Containers (JACC). 58

8.1.3.        JAAS Login Modules. 59

8.1.3.1.          Properties Login Module. 59

8.1.3.2.          Memory Database Login Module. 59

8.1.3.3.          SQL Login Module. 60

8.2.       Getting More Information. 61

9.      JNDI Naming On Siwpas. 62

9.1.       Binding of Web Application Name. 62

9.2.       Binding of EJB Beans. 62

9.2.1.        OpenEJB JNDI Name Formatting. 63

9.2.2.         Configuring the EJB Bean’ JNDI names. 63

9.2.2.1.          Configure Server Level 64

9.2.2.2.          Configure Web Module Level 64

9.2.2.3.          Specific EJB Bean Level 64

9.2.2.4.          Specific EJB Bean’ Interface Type Level 64

9.2.2.5.          Specific EJB Bean’ Individual Interface Level 65

9.2.2.6.          Specific Multiple Jndi Name. 65

9.2.2.7.          Conservative Settings: 65

9.2.2.8.          Pragmatic Settings: 66

9.2.2.9.          Optimistic settings. 66

9.2.2.10.        Collisions of JNDI Names. 66

9.3.       EJB Specification Based Global JNDI Names. 66

9.4.       Default Injectable Resources. 67

10.         Transactions on Siwpas. 69

10.1.          Transaction Manager Overview.. 69

10.1.1.      Configuring the Transaction Manager Identity. 69

10.2.          JTA and Non-JTA Managed DataSources. 70

10.3.          Injection of Transactional Objects. 70

10.4.          Transaction Manager Configuration. 70

10.5.          Using Transaction in EJB Beans, Basic Information. 70

10.5.1.      Basic Rules. 70

10.5.2.      Transaction Attribute Configuration. 71

10.6.          JPA Entity Managers in JTA Transactions. 71

11.         Siwpas Clustering Guide. 73

11.1.          CDI Bean Clustering. 73

11.2.          EJB Stateful Bean Clustering. 74

11.3.          Configuration Parameters. 74

12.         Useful References. 77

Siwpas References. 77

Other References. 77

13.         Licenses. 78

Here is the LGPL v3 License, 78

Here is the ASF v2 License, 81


 

1.     Forward

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

 

© 2008-2011 MechSoft Mechanical and Software Solutions, Cevizlidere Mah. 1235. Cadde 1243. Sok. Taşpınar İş Merkezi No:2/14

Cankaya Ankara, Turkey. All rights reserved.

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”

Or

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”

Or

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