|
Orion documentation overview
The Orion documentation contains several different parts. This overview contains some info on its own but also many references to local and external documentation
1 Introduction
This is the main documentation overview for the Orion Application
Server. It mostly contains links to other documents but it also contains some
documentation itself. It is organized in different sections ordered somewhat
"chronologically" starting with installing Orion and then proceeding
to configuration, development and deployment.
You can download the documentation package
here.
2 Installing Orion
3 Learning the technologies
With Orion being an implementation of the J2EE specification,
understanding the J2EE technologies is very important to be able to use Orion.
These technologies are not Orion specific so many sources of information about
this are available
externally. However, since we try
to implement things as soon as they appear, we need to provide some tutorials
on certain subjects. These are available on the
Tutorials page.
The technologies that are of most interest are the following:
J2EE
EJB
Servlets/JSP
JMS
JNDI
JDBC
JTA
XML/XSL
HTTP
The
external link section contains pointers to where you can find complete information about the covered technologies.
One concept that is very important to understand is the J2EE Application concept.
This is because, in Orion, everything is part of an "application"
(however, to not force the application concept onto developers, you can always
put things in the "default" application instead of creating a new
one.)
You can read about
J2EE Applications, J2EE roles and the Application development lifecycle in Orion here.
4 Configuring Orion
In the J2EE platform, XML is the preferred format for configuration files.
The configuration for applications and components are all XML-based. There are
three kinds of configuration files you will come in contact with when using
Orion.
-
Server configuration. These settings are not related to the user J2EE applications but to the server itself.
-
Generic J2EE application and component configuration.
-
Orion-specific application and component configuration.
The references for these different configurations can be found
here.
How to set up specific things can be found in the sections about development,
debugging and deployment, depending on under which category they fall.
You can also get an alphabetical listing of the tags and attributes in the
configuration files
here. Looking at these is often useful
when you know what setting you want to change but don't know what file to look
in.
5 Developing with Orion
One of the main focuses of Orion has always been to ease development
of enterprise applications. In this section we go through how to develop the
different components for Orion. We also provide a few graphical tools to aid
development and deployment, for tutorials about using these, visit the
tutorials section.
5.1 Developing Web Applications
When developing Web Applications, remember to enable the development
mode. This enables a number of features that simplify development but means
somewhat more overhead in production. You can enable development mode by adding
development="true" in the <orion-web-app> tag in orion/config/global-web-application.xml. A guide for enabling development mode is available
here.
Web applications are built from Servlets, JSPs, Tag libraries and standard Java beans.
5.2 Developing Servlets
Orion provides a feature to auto-compile Servlets when you are using the development mode. This is meant to make the develop-test cycle faster.
You can use any text editor to edit the Servlet and when you make a request to the servlet it is automatically compiled. A guide for how to use this is
available
here.
Of course you can also compile the Servlets using your favorite
IDE or Java compiler. If you do so you simply put the Servlet class in the WEB-INF/classes
directory of your web application. If you do not want to package your Servlets
into a new web application, you can simply put the classes in /orion/default-web-app/WEB-INF/classes/ .
5.3 Developing JSP
JSPs are designed to be very easy to develop. Just put the JSP
in the correct directory and it will be compiled automatically on the first
request to it. Related beans and tag libraries will also be recompiled upon
requests to the JSP if they are available in the web-application file hierarchy.
If development mode is set to true, the JSP is compiled into a Servlet and its
source code is stored in the file foo.jsp.java (if the JSP file is called foo.jsp)
in the chosen persistence-directory. If the persistence-directory hasn't been
altered, it's orion\application-deployments\default\defaultWebApp\persistence
for the default web-application. When you get an exception the stack trace will
tell you both which line number in the JSP and which line number in the servlet
the exception occurred on.
5.4 Developing Tag Libraries
The
Taglibs tutorial thoroughly explains how to develop and use different kinds of tag libraries using Orion.
5.5 Developing EJBs
Assuming that you are familiar with EJB programming in general, the most notable things about Orion are the following:
-
Stubs are generated on demand. You do not need to precompile stubs using
ejbc, rmic or similar. Just deploy your EJBs and use them.
-
Hot Auto-deployment. When you add an application with an EJB module, it
will automatically be deployed and in most cases you will not have to do anything
in the deployment process. Also, when later changing the application you will
not have to redeploy the application or restart the server, the changes will
be picked up automatically
For a reference on Orion specific EJB settings, used for more advanced configurations,
see
orion-ejb-jar.xml, which is the Orion
specific deployment descriptor. In this file you can configure for example:
Call time-outs
The query for CMP finders using the <finder-method> tag.
Transaction retries
Whether Orion has exclusive-write-access to the table for a certain EJB
(the exclusive-write-access attribute in <entity-deployment>.
Transaction isolation
Cache time-outs
you can also override the settings that the auto-deployment sets, like database
table name, data-types for the columns in the database, JNDI names, etc.
Now to more detailed guides about developing the different bean types. You
can also check out the
examples section for more EJB
samples
5.5.1 Session EJBs
The
Orion Primer
thoroughly explains how to develop a session bean and integrate it with a web
application into a full J2EE application.
5.5.2 Entity EJBs with Container Managed Persistence (CMP)
The
Orion CMP Primer explains how to use Entity beans with Container Managed Persistence,
and how to integrate them with a web-application into a full J2EE application.
Orion also supports a few features to simplify your CMP entity bean development:
EJBmaker. This
tutorial
explains how to use the EJBMaker to automatically generate simple CMP Entity
beans.
Auto-generated finders. Orion will automatically generate the finder queries
for findByAll() and findByX() methods. findByAll() will return all entries
in the table and findByX(x) will return all entries where the X column match
the value supplied as a parameter to the method.
OR-mapping. Orion supports a proprietary OR-mapping system you can read
about
here, and also supports the OR-mapping standard
in the EJB 2.0 drafts.
Database-schemas. To make your EJBs totally database-independent, Orion
generates SQL that is based on the database-schema that the deployer has installed
for his database. This means that the code will run unchanged using any database
with a correct database-schema and you can easily modify or write new schemas
for other databases.
5.5.3 Entity EJBs with Bean Managed Persistence (BMP)
Developing Bean Managed Persistence Entity beans works much like
developing CMP Entity beans, except for the obvious differences in persistence
handling. Study how to build a CMP Entity bean and study how BMP Entity beans
work.
5.6 Transactions in Orion
Transactions work in Orion like the EJB and JTA specification
mandates. However there are a few Orion specific settings to using transactions.
These are the max-tx-retries attribute in the <entity-deployment>
and <session-deployment> tags in orion-ejb-jar.xml and the isolation attribute
in <entity-deployment>.
For more information on these, see the
"Deployment settings reference".
5.7
JNDI
When talking to the Orion JNDI tree from outside the container,
you should specify the following JNDI properties (normally in a jndi-properties
file):
java.naming.factory.initial=com.evermind.server.ApplicationClientInitialContextFactory
java.naming.provider.url=ormi://localhost/<domain (application)>
java.naming.security.principal=<username>
java.naming.security.credentials=<password>
|
Listing 1: Sample JNDI Properties
5.8 JDBC
The key to using JDBC in Orion is the use of data sources. Each
database you are operating with is set up as one or more data sources in config/data-sources.xml.
A description and full reference of data-sources.xml is available
here.
Also remember to put the driver (zip/jar) for your database to the /lib directory
in Orion.
When having set up a data-source you can get a reference to a javax.jdbc.DataSource from your code by doing:
new InitialContext().lookup("jdbc/MyEJBDS");
|
Listing 2: Looking up the data-source reference
(where jdbc/MyEJBDS is the name of the data source as specified in data-sources.xml).
If you are looking up a data-source in Orion from outside the
container, you must have use the correct JNDI settings to be able to locate
the data source. See the
JNDI section for information about
this. Orion supports database pooling and transaction, and to make sure that
you use a pooled transactional version of the data source, make sure you use
the ejb-name for the data-source.
5.9
JMS
To configure JMS, see the server configuration for
jms.xml.
There you declare your Queues and Connections. These can be looked up using
JNDI. For example:
QueueConnectionFactory factory = (QueueConnectionFactory) new InitialContext()Lookup("java:comp/env/jms/theQueueConnectionFactory");
QueueConnection connection = factory.createQueueConnection();
Queue queue = (Queue) new InitialContext()Lookup("Java:comp/env/jms/theQueue");
|
Listing 3: Gaining access to the QueueConnection and Queue defined in jms.xml
Will give you access to the QueueConnection and Queue defined
in jms.xml (in this case as jms/theQueueConnectionFactory and jms/theQueue).
For JMS samples, look at orion/demo/jms/
For information about using third party JMS implementations as Resource providers, see the
Resource provider documentation.
5.10
J2EE Application clients
5.11 J2EE Applications
5.12 User Management and Security
|
A separate document is currently being prepared about this subject.
|
6 Debugging applications in Orion
7 Deploying Orion into a production environment
This section talks about questions specific to setting up a real production server.
7.1 SSL
7.2 Logging
7.3 Clustering
7.4 Virtual hosting
7.5 RMI-HTTP tunneling
This article shows to to enable tunneling RMI invocations via HTTP
to get through firewalls only allowing HTTP traffic.
7.6 RMI-HTTPS tunneling
7.7 Protecting one user from another in hosting environments
7.8 Using Third party hosting services/
7.9 Remote access to EJB-modules
8 Orion FAQs
The
official Orion FAQ contains many questions related to development and administration/configuration among other things.
User-contributed FAQ to be added
9 Orion Distribution Overview
An overview of what the orion distribution contains (directories and files and the meaning of these) can be found
here.
10 Examples
11 Orion tools reference
A listing of the tools that are delivered with the Orion distribution, including their usage, can be found
here.
12 Configuration Reference
The reference for all configuration files available in different forms. Here
is a short overview of them, and the complete references are linked here. They
are also available sorted by tag name and attribute name, rather than by file.
You can find the references sorted on tag name and attribute name
here.
12.1 Server XML
The server.xml file contains the configuration for the application-server.
Among other things, this is where you specify:
The library-path
The global application, the global web application and the default web site served.
Maximum number of HTTP connections the server allows
Logging settings
Java compiler settings
Cluster ID
Transaction time-out
SMTP host
The server.xml file also contains references to the other configuration files. Specifically, in the server.xml you specify
Where the data-source configuration is located
Where the principals configuration is located
Where the configuration for JMS and RMI is located
Finally, the server.xml file is where you add your own applications.
12.2 Website XML
The
web-site.xml file contains the configuration for a website Specifically you specify:
Hostname/IP as well as virtual hosts settings for this site,
port to listen and whether it's a secure site (using SSL)
Default web application for this site
Additional web applications for this site
The access-log format
Settings for user web applications (for /~user/ sites)
SSL configuration
12.3 Principals XML
The principals.xml file is the location of user and group configuration when using the default XMLUserManager. It contains
Name and description of users/groups and real name and password for users
Optional X.509 certificates for users
12.4 Data-Sources XML
The data-sources.xml file contains configuration for the data sources used along with an optional reference to a database schema that describes configuration for a specific DataSource type.
Information about data-source configuration can be found here" type="oriondoc and information about database-schemas can be found here.
12.5 JMS XML
The
jms.xml file contains configuration for the Java Messaging Service subsystem. It contains:
The hostname/IP and port the JMS server binds to
Specification of Queues and Topics to be bound in the JNDI tree.
Log settings
12.6 RMI XML
The rmi.xml file contains configuration for Orion's Remote Method Invocation system. In this file you specify:
The hostname/IP and port the RMI server binds to
Remote servers to communicate to
Clustering settings
Log settings
See the
RMI-configuration document for RMI-confinguration details.
12.7 Load balancer XML
13
Deployment settings Reference
As with the server configuration files, the reference for these files can also be found sorted by
tags and by
attributes.
In J2EE there are two kinds of deployment descriptors, or module configuration files.
The generic J2EE deployment files that all application server honor and vendor specific ones.
The generic ones are used by the component and applicationassembler and the vendor specific ones by the deployer.
The Orion specific deployment XML files contains deployment information for different components.
The files are automatically generated when using auto-deploymentbut you can edit them manually.
These files are very central and contains lots of configuration possibilities. Make sure you understand these files.
The files are organized as one file per component type and one file for the complete application. These files are described below.
13.1 Orion Application deployment (orion-application.xml)
orion-application.xml contains settings like:
Whether to auto-create and auto-delete tables for CMP beans
The default data-source to use with CMP beans
Security-role mappings
Specifying User-manager
JNDI namespace-access
etc.
13.2 Orion EJB deployment (orion-ejb-jar.xml)
orion-ejb-jar.xml contains for example:
Time-out settings
TX-retry settings
Session persistence settings
TX isolation settings
CMP mappings
OR mappings
Finder method specifications
JNDI mappings
etc.
13.3 Orion Web-application deployment (orion-web.xml)
13.4
Orion Application-client deployment(orion-application-client.xml)
14
J2EE deployment files
The J2EE configuration files are standardized configuration files used across all J2EE servers.
This means that these files are documented in many other places too, for example in the technology specifications.
15 tag Reference
16 XML attribute Reference
17 Orion API documentation
18 J2EE API documentation
19 J2EE Specifications
20 External links
20.1 Orion related sites
20.2 The Sun Java website (java.sun.com)
20.3
Cetus-links
20.4
Misc. links
20.5 J2EE dicussion forums
Copyright ©
2005 IronFlare AB
|