Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Jetty/Feature/Start.jar"
| Line 14: | Line 14: | ||
The start.jar mechanism is an executable jar file that will build a class path and then execute your main program. It is a generic mechanism that can be used with any java program and it's behaviour is controlled by a [http://dev.eclipse.org/svnroot/rt/org.eclipse.jetty/jetty/trunk/jetty-start/src/main/resources/org/eclipse/jetty/start/start.config start.config] file. The standard start.jar comes with a [http://dev.eclipse.org/svnroot/rt/org.eclipse.jetty/jetty/trunk/jetty-start/src/main/resources/org/eclipse/jetty/start/start.config start.config] file for jetty, so that you can start jetty with: | The start.jar mechanism is an executable jar file that will build a class path and then execute your main program. It is a generic mechanism that can be used with any java program and it's behaviour is controlled by a [http://dev.eclipse.org/svnroot/rt/org.eclipse.jetty/jetty/trunk/jetty-start/src/main/resources/org/eclipse/jetty/start/start.config start.config] file. The standard start.jar comes with a [http://dev.eclipse.org/svnroot/rt/org.eclipse.jetty/jetty/trunk/jetty-start/src/main/resources/org/eclipse/jetty/start/start.config start.config] file for jetty, so that you can start jetty with: | ||
| − | |||
<source lang="bash"> | <source lang="bash"> | ||
java -jar start.jar | java -jar start.jar | ||
</source> | </source> | ||
| − | + | You can see the effective command line generated by start.jar by providing the --dry-run parameter: | |
| + | <source lang="bash"> | ||
| + | java -jar start.jar --dry-run | ||
| + | </source> | ||
| + | which for the default case generates: | ||
| + | <source lang="text"> | ||
| + | /usr/lib/jvm/java-1.5.0-sun-1.5.0.19/jre/bin/java \ | ||
| + | -Djetty.home=/home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution \ | ||
| + | -cp /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/resources:\ | ||
| + | /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-xml-7.0.0.RC6-SNAPSHOT.jar:\ | ||
| + | /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/servlet-api-2.5.jar:\ | ||
| + | /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-http-7.0.0.RC6-SNAPSHOT.jar:\ | ||
| + | /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-continuation-7.0.0.RC6-SNAPSHOT.jar:\ | ||
| + | /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-server-7.0.0.RC6-SNAPSHOT.jar:\ | ||
| + | /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-security-7.0.0.RC6-SNAPSHOT.jar:\ | ||
| + | /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-servlet-7.0.0.RC6-SNAPSHOT.jar:\ | ||
| + | /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-webapp-7.0.0.RC6-SNAPSHOT.jar:\ | ||
| + | /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-deploy-7.0.0.RC6-SNAPSHOT.jar:\ | ||
| + | /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-servlets-7.0.0.RC6-SNAPSHOT.jar:\ | ||
| + | /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-util-7.0.0.RC6-SNAPSHOT.jar:\ | ||
| + | /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-io-7.0.0.RC6-SNAPSHOT.jar \ | ||
| + | org.eclipse.jetty.xml.XmlConfiguration \ | ||
| + | /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/etc/jetty.xml | ||
| + | </source> | ||
| + | |body= | ||
=== Building the environment === | === Building the environment === | ||
| − | |||
The start.jar builds and environment of java system properties and start properties that are used to parameterize the start mechanism and the execution of the program. In a start.config, the string ${name} is expanded to a start property and $(name) is expanded to either a start property or a system property. | The start.jar builds and environment of java system properties and start properties that are used to parameterize the start mechanism and the execution of the program. In a start.config, the string ${name} is expanded to a start property and $(name) is expanded to either a start property or a system property. | ||
| Line 28: | Line 50: | ||
The $(version) property is also determined by examining the manifest of the start.jar. | The $(version) property is also determined by examining the manifest of the start.jar. | ||
| − | |||
=== Building the classpath === | === Building the classpath === | ||
| − | |||
The default start.config assumes that all the jetty jars will be in a directory tree under ${jetty.home}/lib The following jars are put on all classpaths built by the default start.config: | The default start.config assumes that all the jetty jars will be in a directory tree under ${jetty.home}/lib The following jars are put on all classpaths built by the default start.config: | ||
<source lang="text"> | <source lang="text"> | ||
| Line 72: | Line 92: | ||
* <b>Known module options</b> - The main known jetty modules each have an option predefined to select their required jars. Known options include xml,server, security, servlet, webapp, deploy, serlvets, rewrite, jmx, ajp, jndi, annotations, setuid, policy and client. | * <b>Known module options</b> - The main known jetty modules each have an option predefined to select their required jars. Known options include xml,server, security, servlet, webapp, deploy, serlvets, rewrite, jmx, ajp, jndi, annotations, setuid, policy and client. | ||
* <b>Discovered options</b> - Directories within ${jetty.home}/lib can be discovered as options. The "lib/ext", "lib/jsp" and "lib/jta" are directories that may be discovered as an options | * <b>Discovered options</b> - Directories within ${jetty.home}/lib can be discovered as options. The "lib/ext", "lib/jsp" and "lib/jta" are directories that may be discovered as an options | ||
| + | |||
=== Building the arguments === | === Building the arguments === | ||
| + | The jetty start.config file lists has etc/jetty.xml as the default command line argument, which in the default case is the name of the configuration file passed to the XmlConfiguration main. If additional configuration files are needed, then all the configuration files must be listed on the command line along with the OPTIONs required for the classpath. For example, the following will run jetty with JMX and AJP connector: | ||
| + | <source lang="bash"> | ||
| + | java -jar start.jar OPTIONS=Server,jmx,ajp etc/jetty-jmx.xml etc/jetty.xml etc/jetty-ajp.xml | ||
| + | </source> | ||
| − | + | Using the --help parameter will list the available XML configuration files. | |
| − | + | ||
| + | === Running the main === | ||
| + | The jetty start.config has org.eclipse.jetty.xml.XmlConfiguration as the main class to run. This can be replaced by another class by setting the start.class system property. | ||
}} | }} | ||
Revision as of 01:53, 16 September 2009
Contents
Introduction
Jetty is just a java program that can be run like any other java program once a classpath has been setup. For example, the SimplestServer from the Embedding Jetty could be run as follows:
java -cp $JETTY_CLASSPATH org.eclipse.jetty.embedded.SimplestServer
Similarly if you configure your server with jetty.xml rather than a java main, then the server can be run with:
java -cp $JETTY_CLASSPATH org.eclipse.jetty.xml.XmlConfiguration etc/jetty.xml
The difficult part of both these examples is knowing what must be on the JETTY_CLASSPATH. The jetty server comes in over 46 jars, so working out exactly which are needed can be difficult. If you develop with maven, these jar dependencies can be managed for you, but you still need to setup a classpath when running from the command line.
The start.jar mechanism is an executable jar file that will build a class path and then execute your main program. It is a generic mechanism that can be used with any java program and it's behaviour is controlled by a start.config file. The standard start.jar comes with a start.config file for jetty, so that you can start jetty with:
java -jar start.jarYou can see the effective command line generated by start.jar by providing the --dry-run parameter:
java -jar start.jar --dry-run
which for the default case generates:
/usr/lib/jvm/java-1.5.0-sun-1.5.0.19/jre/bin/java \ -Djetty.home=/home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution \ -cp /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/resources:\ /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-xml-7.0.0.RC6-SNAPSHOT.jar:\ /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/servlet-api-2.5.jar:\ /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-http-7.0.0.RC6-SNAPSHOT.jar:\ /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-continuation-7.0.0.RC6-SNAPSHOT.jar:\ /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-server-7.0.0.RC6-SNAPSHOT.jar:\ /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-security-7.0.0.RC6-SNAPSHOT.jar:\ /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-servlet-7.0.0.RC6-SNAPSHOT.jar:\ /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-webapp-7.0.0.RC6-SNAPSHOT.jar:\ /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-deploy-7.0.0.RC6-SNAPSHOT.jar:\ /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-servlets-7.0.0.RC6-SNAPSHOT.jar:\ /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-util-7.0.0.RC6-SNAPSHOT.jar:\ /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/lib/jetty-io-7.0.0.RC6-SNAPSHOT.jar \ org.eclipse.jetty.xml.XmlConfiguration \ /home/gregw/src/jetty-7.0.0/jetty-distribution/target/distribution/etc/jetty.xml
Feature
Building the environment
The start.jar builds and environment of java system properties and start properties that are used to parameterize the start mechanism and the execution of the program. In a start.config, the string ${name} is expanded to a start property and $(name) is expanded to either a start property or a system property.
The main property set by the default start.config is jetty.home, which is assumed to be the directory in which start.jar is deployed. If the jetty.home is not set with a -Djetty.home then ".", ".." and some well known directories are searched for start.jar
The $(version) property is also determined by examining the manifest of the start.jar.
Building the classpath
The default start.config assumes that all the jetty jars will be in a directory tree under ${jetty.home}/lib The following jars are put on all classpaths built by the default start.config:
$(jetty.home)/lib/jetty-util-$(version).jar $(jetty.home)/lib/jetty-io-$(version).jar
If no OPTION are specified, then the following entries are also added by default:
$(jetty.home)/resources/ $(jetty.home)/lib/jetty-xml-$(version).jar $(jetty.home)/lib/servlet-api-2.5.jar $(jetty.home)/lib/jetty-http-$(version).jar $(jetty.home)/lib/jetty-continuation-$(version).jar $(jetty.home)/lib/jetty-server-$(version).jar $(jetty.home)/lib/jetty-security-$(version).jar $(jetty.home)/lib/jetty-servlet-$(version).jar $(jetty.home)/lib/jetty-webapp-$(version).jar $(jetty.home)/lib/jetty-deploy-$(version).jar $(jetty.home)/lib/jetty-servlets-$(version).jar $(jetty.home)/lib/ext/*.jar
This is sufficient to run most standard web applications.
If the system property ${path} is defined, then it is treated as a classpath string and prepended to the generated classpath. If the system property ${lib} is defined, then it is treated as a directory of jars and all jars discovered are prepended to the generated classpath.
OPTIONS
Options may be specified to the start.jar to change the default jars added to the classpath:
java -jar start.jar OPTIONS=Server,jmx,ajp,setuid
The available options may be listed with
java -jar start.jar --help
If an option is specified, then the default jars listed above are not added to the classpath. There are three types of options available:
- Convenience Options - By convention, options starting with a capital letter are convenience options that include many other options. For example the "Server" option includes all the options commonly needed to run a server: xml,server,security,servlet,webapp,deploy and servlets options; while the option "server" contains just the jars for the core HTTP server. "All" is the other convenience option.
- Known module options - The main known jetty modules each have an option predefined to select their required jars. Known options include xml,server, security, servlet, webapp, deploy, serlvets, rewrite, jmx, ajp, jndi, annotations, setuid, policy and client.
- Discovered options - Directories within ${jetty.home}/lib can be discovered as options. The "lib/ext", "lib/jsp" and "lib/jta" are directories that may be discovered as an options
Building the arguments
The jetty start.config file lists has etc/jetty.xml as the default command line argument, which in the default case is the name of the configuration file passed to the XmlConfiguration main. If additional configuration files are needed, then all the configuration files must be listed on the command line along with the OPTIONs required for the classpath. For example, the following will run jetty with JMX and AJP connector:
java -jar start.jar OPTIONS=Server,jmx,ajp etc/jetty-jmx.xml etc/jetty.xml etc/jetty-ajp.xml
Using the --help parameter will list the available XML configuration files.
Running the main
The jetty start.config has org.eclipse.jetty.xml.XmlConfiguration as the main class to run. This can be replaced by another class by setting the start.class system property.