Difference between revisions of "Jetty/Feature/Start.jar"

From Eclipsepedia

< Jetty‎ | Feature
Jump to: navigation, search
m
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{Jetty Feature
 
{{Jetty Feature
|introduction=Jetty is just a Java program that can be run like any other Java program once you set up a classpath. For example, the SimplestServer from the [[Jetty/Tutorial/Embedding_Jetty|Embedding Jetty Tutorial]] can be run as follows:
+
|introduction=
 +
 
 +
{{Jetty Redirect|http://www.eclipse.org/jetty/documentation/current/advanced-jetty-start.html}}
 +
 
 +
Jetty is just a Java program that you can run like any other Java program once you set up a classpath. For example, you can run the SimplestServer from the [[Jetty/Tutorial/Embedding_Jetty|Embedding Jetty Tutorial]] as follows:
 
<source lang="bash">
 
<source lang="bash">
 
java -cp $JETTY_CLASSPATH org.eclipse.jetty.embedded.SimplestServer
 
java -cp $JETTY_CLASSPATH org.eclipse.jetty.embedded.SimplestServer
 
</source>
 
</source>
  
Similarly, if you configure your server with [[Jetty/Reference/jetty.xml_syntax|jetty.xml]] rather than a Java main, the server can be run with:
+
Similarly, if you configure your server with [[Jetty/Reference/jetty.xml_syntax|<tt>jetty.xml</tt>]] rather than a Java main, you can run the server with:
  
 
<source lang="bash">
 
<source lang="bash">
Line 11: Line 15:
 
</source>
 
</source>
  
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 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 Jars you need can be difficult. If you develop with Maven, these Jar dependencies can be managed for you, but you still need to set up a classpath when running from the command line.
  
The start.jar mechanism is an executable jar file that builds a class path and then executes your main program. It is a generic mechanism that you can use with any Java program. Its 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 <tt>start.jar</tt> mechanism is an executable Jar file that builds a class path and then executes your main program. It is a generic mechanism that you can use with any Java program. A [http://git.eclipse.org/c/jetty/org.eclipse.jetty.project.git/plain/jetty-start/src/main/resources/org/eclipse/jetty/start/start.config <tt>start.config</tt>] file controls its behaviour.  The standard <tt>start.jar</tt> comes with a <tt>start.config</tt> 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:
+
You can see the effective command line <tt>start.jar</tt> generates by providing the --dry-run parameter:
 
<source lang="bash">
 
<source lang="bash">
 
java -jar start.jar --dry-run
 
java -jar start.jar --dry-run
Line 45: Line 49:
 
|body=
 
|body=
 
== Building the Environment ==
 
== Building the Environment ==
The start.jar builds an environment of Java system properties and start properties that 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 <tt>start.jar</tt> builds an environment of Java system properties and start properties that parameterize the start mechanism and the execution of the program. In a [http://git.eclipse.org/c/jetty/org.eclipse.jetty.project.git/plain/jetty-start/src/main/resources/org/eclipse/jetty/start/start.config <tt>start.config</tt>], the string <tt>${name}</tt> is expanded to a start property and <tt>$(name)</tt> 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 main property set by the default <tt>start.config</tt> is <tt>jetty.home</tt>, which is assumed to be the directory in which <tt>start.jar</tt> is deployed.  If the <tt>jetty.home</tt> is not set with a <tt>-Djetty.home</tt>, then ".", ".." and some well known directories are searched for <tt>start.jar</tt>.
  
The $(version) property is also determined by examining the manifest of the start.jar.
+
The <tt>$(version)</tt> property is also determined by examining the manifest of the <tt>start.jar</tt>.
  
 
== 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 <tt>start.config</tt> assumes that all the Jetty Jars are in a directory tree under <tt>${jetty.home}/lib</tt>. The following Jars are put on all classpaths built by the default start.config:
 
<source lang="text">  
 
<source lang="text">  
 
$(jetty.home)/lib/jetty-util-$(version).jar
 
$(jetty.home)/lib/jetty-util-$(version).jar
Line 58: Line 62:
 
</source>
 
</source>
  
If you don't specify any OPTIONS, then the following entries are also added by default:
+
If you don't specify any OPTIONS, the following entries are also added by default:
 
<source lang="text">  
 
<source lang="text">  
 
$(jetty.home)/resources/
 
$(jetty.home)/resources/
Line 75: Line 79:
 
This is sufficient to run most standard web applications.
 
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.
+
If the system property <tt>${path}</tt> is defined, it is treated as a classpath string and prepended to the generated classpath. If the system property <tt>${lib}</tt> is defined, it is treated as a directory of Jars and all Jars discovered are prepended to the generated classpath.
  
 
=== Setting OPTIONS ===
 
=== Setting OPTIONS ===
You can specify options to the start.jar to change the default jars added to the classpath:
+
You can specify options to the <tt>start.jar</tt> to change the default Jars added to the classpath:
 
<source lang="bash">
 
<source lang="bash">
 
java -jar start.jar OPTIONS=Server,jmx,ajp,setuid
 
java -jar start.jar OPTIONS=Server,jmx,ajp,setuid
 
</source>
 
</source>
  
The available options can be listed with
+
To list the options available, use:
 
<source lang="bash">
 
<source lang="bash">
 
java -jar start.jar --help
 
java -jar start.jar --help
 
</source>
 
</source>
  
If an option is specified, then the default jars listed above are not added to the classpath. There are three types of options available:
+
If you specify an option, the default Jars listed above are not added to the classpath.
* <b>Convenience Options</b>–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.
+
 
* <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.
+
Three types of options are available:
* <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 can be discovered as an options
+
* <b>Convenience Options</b>–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.
 +
* <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 <tt>${jetty.home}/lib</tt> can be discovered as options. The "lib/ext", "lib/jsp" and "lib/jta" are directories that can 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 runs Jetty with JMX and AJP connector:
+
The jetty [http://git.eclipse.org/c/jetty/org.eclipse.jetty.project.git/plain/jetty-start/src/main/resources/org/eclipse/jetty/start/start.config <tt>start.config</tt>] file lists has <tt>etc/jetty.xml</tt> as the default command line argument, which in the default case is the name of the configuration file passed to the XmlConfiguration main. If you need additional configuration files, you must list all the configuration files on the command line along with the options required for the classpath. For example, the following runs Jetty with JMX and AJP connector:
 
<source lang="bash">
 
<source lang="bash">
 
java -jar start.jar OPTIONS=Server,jmx,ajp etc/jetty-jmx.xml etc/jetty.xml etc/jetty-ajp.xml
 
java -jar start.jar OPTIONS=Server,jmx,ajp etc/jetty-jmx.xml etc/jetty.xml etc/jetty-ajp.xml
 
</source>
 
</source>
  
Use the --help parameter to list the available XML configuration files.
+
Use the <tt>--help</tt> parameter to list the available XML configuration files.
  
 
== Running the Main ==
 
== Running the Main ==
The jetty start.config has org.eclipse.jetty.xml.XmlConfiguration as the main class to run.  You can replace it with another class by setting the start.class system property.
+
The jetty <tt>start.config</tt> has <tt>org.eclipse.jetty.xml.XmlConfiguration</tt> as the main class to run.  You can replace it with another class by setting the <tt>start.class</tt> system property.
  
  
 
== Setting Defaults: start.ini ==
 
== Setting Defaults: start.ini ==
  
If the file "start.ini" exists in the same directory as start.jar, then it is read and every non comment line is treated as a command line argument.  The following start.ini sets the options and default configuration files for using the server with JMX and SSL:
+
If the file <tt>start.ini</tt> exists in the same directory as <tt>start.jar</tt>, it is read and every non-comment line is treated as a command line argument.  The following <tt>start.ini</tt> sets the options and default configuration files for using the server with JMX and SSL:
 
<source lang="bash">
 
<source lang="bash">
 
#===========================================================
 
#===========================================================
Line 119: Line 125:
 
</source>
 
</source>
  
As well as normal start.jar arguments, it is possible to put JVM arguments in a start.ini.  However, because these cannot affect the JVM that is running start.jar, the --exec option should be provided so that a new JVM is spawned with the arguments.  The following start.ini example sets the JVM heap memory and enables remote JMX management:
+
As well as normal <tt>start.jar</tt> arguments, it is possible to put JVM arguments in a <tt>start.ini</tt>.  However, because these cannot affect the JVM that is running <tt>start.jar</tt>, you should provide the <tt>--exec</tt> option so that a new JVM is spawned with the arguments.  The following <tt>start.ini</tt> example sets the JVM heap memory and enables remote JMX management:
 
<source lang="bash">
 
<source lang="bash">
 
#===========================================================
 
#===========================================================

Latest revision as of 13:55, 23 April 2013



Contents

[edit] Introduction


Jetty is just a Java program that you can run like any other Java program once you set up a classpath. For example, you can run the SimplestServer from the Embedding Jetty Tutorial 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, you can run the server 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 Jars you need can be difficult. If you develop with Maven, these Jar dependencies can be managed for you, but you still need to set up a classpath when running from the command line.

The start.jar mechanism is an executable Jar file that builds a class path and then executes your main program. It is a generic mechanism that you can use with any Java program. A start.config file controls its behaviour. The standard start.jar comes with a start.config file for Jetty, so that you can start Jetty with:

java -jar start.jar

You can see the effective command line start.jar generates 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

[edit] Feature

Building the Environment

The start.jar builds an environment of Java system properties and start properties that 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 are 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 you don't specify any OPTIONS, 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, it is treated as a classpath string and prepended to the generated classpath. If the system property ${lib} is defined, it is treated as a directory of Jars and all Jars discovered are prepended to the generated classpath.

Setting OPTIONS

You can specify options to the start.jar to change the default Jars added to the classpath:

java -jar start.jar OPTIONS=Server,jmx,ajp,setuid

To list the options available, use:

java -jar start.jar --help

If you specify an option, the default Jars listed above are not added to the classpath.

Three types of options are 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 can 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 you need additional configuration files, you must list all the configuration files on the command line along with the options required for the classpath. For example, the following runs 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

Use the --help parameter to 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. You can replace it with another class by setting the start.class system property.


Setting Defaults: start.ini

If the file start.ini exists in the same directory as start.jar, it is read and every non-comment line is treated as a command line argument. The following start.ini sets the options and default configuration files for using the server with JMX and SSL:

#===========================================================
# Jetty start.jar arguments
#-----------------------------------------------------------
OPTIONS=Server,jmx,resources
etc/jetty-jmx.xml
etc/jetty.xml
etc/jetty-ssl.xml

As well as normal start.jar arguments, it is possible to put JVM arguments in a start.ini. However, because these cannot affect the JVM that is running start.jar, you should provide the --exec option so that a new JVM is spawned with the arguments. The following start.ini example sets the JVM heap memory and enables remote JMX management:

#===========================================================
# Jetty start.jar arguments
#-----------------------------------------------------------
--exec
-Xmx512m
-Dcom.sun.management.jmxremote
OPTIONS=Server,jmx,resources
etc/jetty-jmx.xml
etc/jetty.xml
etc/jetty-ssl.xml