<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="admin.use" xml:lang="en"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:mml="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>Using JonasAdmin</title>
  </info>

  <para>Once started, JonasAdmin can administer the JOnAS server in which it
  is running. If the host server is a master, JonasAdmin can also administer
  the rest of the servers running in the domain.</para>

  <section xml:id="Admin-JonasAdminRun">
    <info>
      <title>Running JonasAdmin</title>
    </info>

    <para>Once the JonasAdmin application deployed on a server, the
    administration console is accessible at the URL: 
    <code>http://&lt;hostname&gt;:&lt;portnumber&gt;/jonasAdmin/</code> using any web
    browser.</para>

    <para>&lt;hostname&gt; is the name of the host where the Servlet container
    is running and &lt;portnumber&gt; is the http port number (default is
    9000).</para>

    <para>After logging in, the left-hand frame in the Welcome page displays
    the management tree associated with the JOnAS server running JonasAdmin.
    The management tree's root is <code> Domain </code> , which allows to the
    domain management facilities in case of a master server.</para>

    <para>In the image below, JonasAdmin is running on the master server named
    <emphasis role="bold">jonas</emphasis> within a domain also named
    <emphasis role="bold">jonas</emphasis>. It is immediately apparent that
    this is a master server, as we have a <code>Monitoring</code> and a <code>Deployment</code> sub-tree
    under the <code>Domain</code> root node.</para>

    <mediaobject>
      <imageobject>
        <imagedata fileref="../../../resources/images/jonasAdminDomain.gif">
          <info>
            <othercredit class="other" otherclass="srccredit">
              <orgname>???</orgname>

              <contrib>JonasAdmin</contrib>
            </othercredit>
          </info>
        </imagedata>
      </imageobject>
    </mediaobject>

    <para>The management tree in this figure allows access to the following
    main management facilities:</para>

    <itemizedlist>
      <listitem>
        <para>Domain administration with domain level deployment
        facilities.</para>
      </listitem>

      <listitem>
        <para>Current server administration</para>
      <itemizedlist>

          <listitem>
            <para>Server monitoring</para>
          </listitem>

          <listitem>
            <para>Logging management</para>
          </listitem>

          <listitem>
            <para>Communication protocols management</para>
          </listitem>

          <listitem>
            <para>Active services presentation and configuration</para>
          </listitem>

          <listitem>
            <para>Dynamic deployment at the current server level</para>
          </listitem>

          <listitem>
            <para>Resources management</para>
          </listitem>

          <listitem>
            <para>Security management</para>
          </listitem>

        </itemizedlist>
      </listitem>
      <listitem>
        <para>Joram platform administration</para>
      </listitem>

      <listitem>
        <para>MBeans browsing</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <info>
      <title>Server management</title>
    </info>

    <para>Displays general information about the administered JOnAS server,
    including the JMX server and the WEB server, and provides the capability
    of listing the content of the Registry.</para>

    <section>
      <info>
        <title>Server monitoring</title>
      </info>

      <para>Presents memory usage, a count of the threads created by JOnAS,
      and other monitoring information concerning managed services and
      resources.</para>
    </section>

    <section>
      <info>
        <title>Logging management</title>
      </info>

      <para>Allows the administrator to configure the JOnAS Logging system.
      Additionally, if Tomcat is used as the WEB container service
      implementation, it allows creation of new access log valves.</para>
    </section>

    <section>
      <info>
        <title>Communication protocols management</title>
      </info>

      <para>This management facility relates to the integration of Tomcat
      management in JonasAdmin. It currently presents connectors defined in
      the Tomcat configuration and allows for the creation of new HTTP, HTTPS,
      or AJP connectors. Note that the <code> Protocols </code> sub-tree is
      not presented if Jetty is used as the WEB container service
      implementation.</para>
    </section>

    <section>
      <info>
        <title>Active services presentation and configuration</title>
      </info>

      <para>All the active services have a corresponding sub-tree in the
      <code> Services </code> tree.</para>

      <para>Managing the various container services consists of presenting
      information about the components deployed in these containers. New
      components can be deployed using the dynamic deployment facilities
      presented in the next section.</para>

      <para>Similarly, the services that allow management of the different
      types of resources (DataSources, Resource Adapters and Mail resources)
      also provide information about the resources being deployed.
      Additionally, deployed resources (DataSources or MailFactories) can be
      reconfigured and their new configuration made persistent by using a
      <code> Save </code> button.</para>

      <para>The transaction service management allows reconfiguration
      (possibly persistent) and presents monitoring information about
      transactions managed by JOnAS.</para>
    </section>

    <section>
      <info>
        <title>Dynamic deployment with JonasAdmin</title>
      </info>

      <para>A very useful management operation is the capability of installing
      (upload), deploying, undeploying or removeing stand-alone J2EE
      components (JAR, WAR, RAR packages) or J2EE applications (EAR packages)
      in the administered server using the <code> Deployment </code>
      sub-tree.</para>

      <para>The administrator's task is facilitated by the display of the list
      of deployable modules, the list of deployed modules, and the capability
      of transferring modules from one list to another (which corresponds to
      <code> deploy/undeploy </code> operations.</para>

      <para>The deployable modules can be installed in directories specific to
      their type, for example, the deployable JARs are un-deployed JARs
      installed in <filename>JONAS_BASE/ejbjars/</filename> directory, or in the
      <filename>JONAS_BASE/deploy</filename> directory.</para>

      <para>The <code> Deployment </code> sub-tree also allows a J2EE package
      to be uploaded from the local file system to the corresponding directory
      of the administered server ( <code> install </code> operation), and the
      opposite <code> remove </code> operation.</para>
    </section>

    <section>
      <info>
        <title>Resources management</title>
      </info>

      <para>The <code>Resources</code> sub-tree provides the capability of
      loading or creating new resources managed by the active services.</para>
    </section>

    <section>
      <info>
        <title>Security management</title>
      </info>

      <para>The <code>Security</code> sub-tree presents existing security
      realms and allows the creation of new realms of different types: memory,
      datasource, and ldap realms.</para>
    </section>
  </section>

  <section>
    <info>
      <title>Note regarding persistent reconfiguration facilities</title>
    </info>

    <para>It is important to note that JOnAS and Tomcat have different
    approaches to reconfiguration persistency. In JOnAS, every
    <code>Save</code> operation is related to a service or a resource
    reconfiguration. For example, the administrator can reconfigure a service
    and a resource, but choose to save only the new resource configuration. In
    Tomcat, the <code>Save</code> operation is global to all configuration
    changes that have been performed. For example, if a new HTTP connector is
    reconfigured and a new context created for a web application, both
    configuration changes are saved when using the <code>Save</code>
    button.</para>
  </section>

  <section>
    <info>
      <title>Domain management</title>
    </info>

    <para>First recall that domain management functions are accessible only
    when JonasAdmin is deployed on a master server. The <code> Domain </code>
    tree contains only one <code> Server </code> sub-tree, the currently
    administered server, which is initially the server hosting
    JonasAdmin.</para>

    <para>Domain management principal function is to present the domain
    topology: list all the servers and clusters belonging to the domain. It
    also allows modification of the domain topology by adding new servers and
    clusters to the domain, removing servers and moving servers to/from
    clusters.</para>

    <para>The domain management page also presents servers that are not yet
    started but are specified as belonging to the domain in the new
    configuration file named <filename> domain.xml </filename> . Also, a server can be
    added to the domain when it has been started without having the discovery
    service enabled.</para>

    <para>An essential domain management function is that the administrator
    can switch from the master to any of the other servers in the domain.
    Currently, JonasAdmin allows only one category of global domain level
    management operation, the <code> deployment </code> operation. Using any
    other management operation requires switching to the server to be
    administered.</para>

    <para>Domain level deployment allows for <code> deploying </code> one or
    more J2EE packages (JARs, WARs, RARs or EARs), which are installed in the
    corresponding master directory (ejbjars, webaps, rars or apps), into any
    running server in the domain. A <code> deployment </code> operation target
    may be a server but also a cluster. The <code> deploy </code> operation
    may have three semantics:</para>

    <itemizedlist>
      <listitem>
        <para>deploy only (create container) - which is useful when the
        package is already installed on the target server.</para>
      </listitem>

      <listitem>
        <para>distribute only - which means install the package in the
        target's corresponding directory</para>
      </listitem>

      <listitem>
        <para>distribute and (re)deploy the package, with optionally replacing
        the current package with the new one.</para>
      </listitem>
    </itemizedlist>

    <para>Note that at domain level deployment the <code> Upload </code> and
    <code> Remove </code> operations are only related to the master server
    itself.</para>
  </section>
</section>
