root/documents/trunk/documentation/src/reference/run-parameters.xml @ 9830

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section SYSTEM "../documentation.dtd">
<section>
  <title>Command line parameters</title>

  <para>The framework's bootstrapper takes care or loading up the Naked
  Objects framework and application, initialising it, and running it. When it
  first starts up it reads in a list of components and attempts to load in
  each one. Any component that can be loaded is then available to be used and
  can then be specified on the command line if it needs to be loaded.
  Requesting a component that cannot be loaded will result in an error. To
  resolve such an error simply ensure that the components Jar file is
  available on the class path. All the components supplied with the framework
  are listed in the file <path>framework.properties</path> which is part of
  the <path>nos-bootstrap.jar</path> file.</para>

  <para>During starting Naked Objects loads in a number of configuration files
  that you can use to configure framework. The main file,
  <path>nakedobjects.properties</path>, is always loaded and must be present
  for the framework to start up. For each of the options type, persistor and
  viewer a separate configuration file is loaded named after the option value.
  For example, for the following command line parameters</para>

  <command-listing>-v dnd -r xml</command-listing>

  <para>the framework looks for the files <path>dnd.properties</path> and
  <path>xml.properties</path> and will load them if found.</para>

  <heading>Available Jars</heading>

  <para>The following are the Jars that are provided with the
  framework:-</para>

  <subheading>Core framework</subheading>

  <list>
    <para>no-application-library-3.0M3.jar</para>

    <para>no-architecture-3.0M3.jar</para>

    <para>nof-core-3.0M3.jar</para>

    <para>nof-persistor-3.0M3.jar</para>

    <para>nof-reflector-core-3.0M3.jar</para>

    <para>nof-reflector-java-3.0M3.jar</para>

    <para>nos-bootstrap-3.0M3.jar</para>

    <para>logging-util-3.0M3.jar</para>
  </list>

  <subheading>Framework extensions</subheading>

  <list>
    <para>nos-objectstore-sql-3.0M3.jar</para>

    <para>nos-objectstore-xml-3.0M3.jar</para>

    <para>nos-viewer-cli-3.0M3.jar</para>

    <para>nos-viewer-dnd-3.0M3.jar</para>

    <para>nos-viewer-html-3.0M3.jar</para>

    <para>nos-web-server-3.0M3.jar</para>

    <para>nos-xat-framework-3.0M3.jar</para>
  </list>

  <subheading>3rd Party</subheading>

  <list>
    <para>junit-3.8.1.jar</para>

    <para>commons-cli-1.0.jar</para>

    <para>log4j-1.2.8.jar</para>

    <para>jetty-6.0.2.jar</para>

    <para>jetty-util-6.0.2.jar</para>

    <para>servlet-api-2.5-6.0.2.jar</para>
  </list>

  <subheading></subheading>

  <subheading>Hibernate</subheading>

  <list>
    <para>antlr-2.7.6.jar</para>

    <para>asm-1.5.3.jar</para>

    <para>asm-attrs-1.5.3.jar</para>

    <para>c3p0-0.9.0.jar</para>

    <para>cglib-2.1_3.jar</para>

    <para>commons-collections-2.1.1.jar</para>

    <para>commons-lang-1.0.jar</para>

    <para>commons-logging-1.0.4.jar</para>

    <para>commons-logging-1.0.jar</para>

    <para>dom4j-1.6.1.jar</para>

    <para>easymock-1.2_Java1.3.jar</para>

    <para>ehcache-1.2.3.jar</para>

    <para>freemarker-2.3.4.jar</para>

    <para>geronimo-spec-jta-1.0.1B-rc1.jar</para>

    <para>hibernate-3.2.1.ga.jar</para>

    <para>hibernate-annotations-3.2.0.ga.jar</para>

    <para>hibernate-tools-3.2.0.beta8.jar</para>

    <para>hsqldb-1.8.0.7.jar</para>

    <para>jta-1.0.1B.jar</para>

    <para>jtidy-r8-21122004.jar</para>

    <para>nos-objectstore-hibernate-3.0M3.jar</para>

    <para>persistence-api-1.0.jar</para>
  </list>

  <comment>TODO add list of Jars and indication of what each is for</comment>

  <heading>Options</heading>

  <para>The bootstrapper is the class
  <class>org.nakedobjects.nof.boot.NakedObjects</class> and takes the
  following options on the command line.</para>

  <subheading>Configuration</subheading>

  <command-listing>-c &lt;config file&gt;
--config &lt;config file&gt;</command-listing>

  <para>Loads in the specified configuration file, in additon to
  <path>nakedobjects.properties</path> and the properties files relating to
  component.</para>

  <subheading>Disable splash</subheading>

  <command-listing>-s
--nosplash</command-listing>

  <para>Prevents the splash screen from being displayed during start
  up.</para>

  <subheading>Help</subheading>

  <command-listing>-h
--help</command-listing>

  <para>Prints out the options that are available. This is dynamic so that
  only the components that can be used are listed.</para>

  <subheading>Logging</subheading>

  <para>The amount of logging detail can be controlled from the command line.
  If no flag is specified only warnings and errors are output. All logging
  level relate to the Log4J levels, which is the logging mechanism used by
  Naked Objects.</para>

  <command-listing>-quiet</command-listing>

  <para>Quiet reduces logging to show errors only.</para>

  <command-listing>-verbose</command-listing>

  <para>Increases logging to show information about the system as it
  runs.</para>

  <command-listing>-debug</command-listing>

  <para>Increases logging to show all logged entries. This level is very
  verbose and will slow down the system if used when outputting log details to
  the console.</para>

  <subheading>Mode</subheading>

  <command-listing>-t &lt;mode&gt;
--type &lt;mode&gt;</command-listing>

  <para>The mode the framwork is started up in must be one of the following,
  and defaults to <ital>prototype</ital>.</para>

  <para><ital>exploration</ital> - Exploration mode is for developers to
  explore and test their code. The framework always uses an in-memory
  persistor and runs the fixtures at startup to ensure a known state every
  time the system is started. The user is not prompted to log in, but is
  automatically logged in as user 'explore'. The logged in user can be changed
  on the fly using an option with the user interface; this simply changes the
  user and does not require an explicit login action. Also, exploration
  methods defined in the DOM are also available to the user to do thing things
  that a user would not normally be allowed to do. These are used for
  expressly for testing the system. Please note it is an error to specify a
  persistor type in exploration mode.</para>

  <para><ital>prototype</ital> - Prototype mode is for demonstrating the
  system in realistic fashion. The framework always uses an in-memory
  persistor and runs the fixtures at startup to ensure a known state every
  time the system is started. The user is always prompted to log in at start
  up, and can log out and log in again without losing the state of the
  objects. This allows a user to demonstrate exactly how a system would work.
  Please note it is an error to specify a persistor type in prototype
  mode.</para>

  <para><ital>standalone</ital> - Standalone mode runs the system for a single
  user with object persistence.</para>

  <para><ital>client</ital> - Client mode provides multiple users access to a
  server. With this mode selected the <ital>connection</ital> option must also
  be specified.</para>

  <para><ital>server</ital> - Server mode runs Naked Objects as a server for
  multiple clients. With this mode selected the <ital>connection</ital> option
  must also be specified.</para>

  <subheading>Overridden properties</subheading>

  <command-listing>-D property=value
</command-listing>

  <para>Using this flag we can pass in properties from the command line that
  would otherwise need to specified in a configuration file. This is normally
  used to override a property, or to temporarily specify one.</para>

  <subheading>Password</subheading>

  <command-listing>-p &lt;password&gt;
--password &lt;password&gt;</command-listing>

  <para>Ignored if type is prototype or not used with the user option
  below.</para>

  <para>Uses the specified password when logging the user in with the username
  specified with <property>--user</property>.</para>

  <subheading>Persistor</subheading>

  <command-listing>-r &lt;persistor&gt;
--persistor &lt;persistor&gt;</command-listing>

  <para>Ignored if type is prototype or client.</para>

  <para>The persistor option allows you choose how the objects created by the
  system will be persisted so they are still available next time you run the
  system. The following options are available with current distribution, and
  if none is specified then the xml persistor will be used by default.</para>

  <para><ital>in-memory</ital> - A simple non-persisting mechanism that will
  only hold the persisted object while the virtual machine is running. This is
  used for testing and demonstrating.</para>

  <para><ital>xml</ital> - A simple file based mechanism that encodes each
  objects data in an XML file. Alongside the data files for the objects are
  instance lists listing all the files for each type of object.</para>

  <para><ital>sql</ital> - A simple JDBC based mechanism that creates basic
  tables for each object type and uses these to store the object's
  data.</para>

  <para><ital>hibernate</ital> - Interface to Hibernate ORM, allowing
  automatic persistence of an entire DOM with the power and flexibility that
  Hibernate provides.</para>

  <para><ital>&lt;class name&gt;</ital> - By specifying a class name the boot
  loader will load up that class as the persistor.</para>

  <subheading>Remote connection</subheading>

  <command-listing>-x &lt;connector&gt;
--connection &lt;connector&gt;</command-listing>

  <para>Ignored if mode is neither a client or server. If the type is either
  server or client then a connection mechanism can be specified. Connector
  mechanisms available are:-</para>

  <para><ital>xstream</ital> - Uses the Xstream library to
  serialize/deserialize objects to/from XML for simple stream
  communications.</para>

  <para><ital>web</ital> - opens a HTTP listener for processing requests from
  web browsers. This can be used to run the framework as a basic web
  server.</para>

  <subheading>User</subheading>

  <command-listing>-u &lt;user name&gt;
--user &lt;user name&gt;</command-listing>

  <para>Ignored if type is prototype.</para>

  <para>Uses the specified name when logging the user in. If the password is
  also specified (see above) then an attempt to log in using the supplied user
  name and password is made; authentication failure at this point will exit
  the program.</para>

  <subheading>Viewer</subheading>

  <command-listing>-v &lt;viewer&gt;
--viewer &lt;viewer&gt;</command-listing>

  <para>Ignored if type is server.</para>

  <para>The viewer option allows you to choose the user interface that is used
  to access your Naked Objects application. The following options are
  available with current distribution, and if none is specified then the drag
  and drop view will be used by default.</para>

  <para><ital>dnd</ital> - Drag and Drop viewer</para>

  <para><ital>cli</ital> - Console based Command Line Interface</para>

  <para><ital>cli-awt</ital> -Command Line Interface running via a basic Java
  AWT window</para>

  <para><ital>web</ital> - Web browser viewer - accessed via standard web
  browser such as FireFox, Internet Explora or Opera</para>

  <para><ital>&lt;class name&gt;</ital> - By specifying a class name the boot
  loader will load up that class as the viewer</para>
</section>