<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<!--

  PDL HEADER START

  Public Documentation License Notice

  The contents of this Documentation are subject to the Public

  Documentation License Version 1.01 (the "License"); you may only

  use this Documentation if you comply with the terms of this License.

  A copy of the License is available at

  http://www.opensolaris.org/os/community/documentation/license.

  PDL HEADER END

  Copyright (c) 2011, 2012, Oracle and/or its affiliates. All rights reserved.

-->

<section>

  <title>Java/JMX Client</title>

<!-- Files -->

<!-- Java Packages -->

  <section>

    <title>Connecting to the RAD server</title>

    <para>

      Connections to a RAD server in Java are made through JMX.  A JMX

      connection is established with:

    </para>

    <orderedlist>

      <listitem>

        a <code>javax.management.remote.JMXServiceURL</code> that identifies the

        protocol to be used, and a host, port, and path where appropriate

      </listitem>

      <listitem>

        a <code>Map&lt;String, Object></code> of protocol-specific options,

        where appropriate

      </listitem>

    </orderedlist>

    <para>

      Several protocols for connecting to a RAD server are supported and are

      defined in the <code>com.oracle.solaris.rad.jmx</code> class.  Unless

      explicitly mentioned, a host, port, path, or options is not applicable:

    </para>

    <variablelist>

      <varlistentry>

        <term>

          RadConnector.PROTOCOL_UNIX

        </term>

        <listitem>

          <para>

            A local UNIX domain socket connection.  The path is the

            fully-qualified name of the socket.

          </para>

          <example>

            <title>RadConnector.PROTOCOL_UNIX</title>

            <programlisting>

JMXServiceURL url = new JMXServiceURL(RadConnector.PROTOCOL_UNIX,

  "", 0, "/system/volatile/rad/radsocket");

JMXConnector connector = JMXConnectorFactory.connect(url);

            </programlisting>

          </example>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>

          RadConnector.PROTOCOL_TCP

        </term>

        <listitem>

          <para>

            A local/remote TCP connection.  A host and/or port may be

            specified.

          </para>

          <example>

            <title>RadConnector.PROTOCOL_TCP</title>

            <programlisting>

JMXServiceURL url = new JMXServiceURL(RadConnector.PROTOCOL_TCP,

    "myhost", 0);

JMXConnector connector = JMXConnectorFactory.connect(url);

            </programlisting>

          </example>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>

          RadConnector.PROTOCOL_TLS

        </term>

        <listitem>

          <para>

            A local/remote TLS connection.  A host and/or port may be

            specified.

          </para>

          <para>

            Expected parameters:

          </para>

          <variablelist>

            <varlistentry>

              <term>

                RadConnector.KEY_TLS_TRUSTSTORE (required)

              </term>

              <listitem>

                <para>

                  the full path to a local RAD truststore file

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>

                RadConnector.KEY_TLS_TRUSTPASS (required)

              </term>

              <listitem>

                <para>

                  the password for the local RAD truststore

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>

                RadConnector.KEY_TLS_RADMANAGER (required)

              </term>

              <listitem>

                <para>

                  an instance of

                  <code>com.oracle.solaris.rad.RadTrustManager</code> for key

                  management

                </para>

              </listitem>

            </varlistentry>

          </variablelist>

          <example>

            <title>RadConnector.PROTOCOL_TLS</title>

            <programlisting>

Map<String, Object> env = new HashMap<String, Object>();

env.put(RadConnector.KEY_TLS_TRUSTSTORE, "/etc/myapp/truststore");

env.put(RadConnector.KEY_TLS_TRUSTPASS, "trustpass");

JMXServiceURL url = new JMXServiceURL(

    RadConnector.PROTOCOL_TLS, host, 0);

JMXConnector connector = JMXConnectorFactory.newJMXConnector(url, null);

for (;;) {

    RadTrustManager mtm = new RadTrustManager();

    env.put(RadConnector.KEY_TLS_RADMANAGER, mtm);

    try {

        connector.connect(env);

        break;

    } catch (IOException e) {

        X509Certificate[] chain = mtm.getBadChain();

        if (chain == null) {

            throw e;

        }

    }

}

            </programlisting>

          </example>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>

          RadConnector.PROTOCOL_PRIVATE

        </term>

        <listitem>

          <para>

            A local connection to a RAD instance private to this process,

            spawned when the connection is established.  The resulting

            <command>rad</command> communicates through its stdin/stdout.

          </para>

          <para>

            Expected parameters:

          </para>

          <variablelist>

            <varlistentry>

              <term>

                RadConnector.PRIVATE_ROOT (<code>String</code>, optional)

              </term>

              <listitem>

                <para>

                  a full path to prefix the to each relatively-named module in

                  the <code>RadConnector.PRIVATE_MODULES</code> parameter, if

                  specified

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>

                RadConnector.PRIVATE_MODULES (<code>String[]</code>, optional)

              </term>

              <listitem>

                <para>

                  a list of modules to load, as with

                  <command>/usr/lib/rad/rad</command> <option>-M</option>

                  <replaceable>module</replaceable>

                </para>

              </listitem>

            </varlistentry>

            <varlistentry>

              <term>

                RadConnector.PRIVATE_AUXARGS (<code>String[]</code>, optional)

              </term>

              <listitem>

                <para>

                  additional arguments to pass to the spawned

                  <command>rad</command> instance

                </para>

              </listitem>

            </varlistentry>

          </variablelist>

          <example>

            <title>RadConnector.PROTOCOL_PRIVATE</title>

            <programlisting>

Map<String, Object> env = new HashMap<String, Object>();

String[] auxargs = { "-d", "-e", "30" };

String[] modules = { "mod_usermgmt.so", "mod_nameservice.so" };

env.put(RadConnector.PRIVATE_AUXARGS, auxargs);

env.put(RadConnector.PRIVATE_MODULES, modules);

env.put(RadConnector.PRIVATE_ROOT, "/usr/share/modules");

JMXServiceURL url = new JMXServiceURL(

    RadConnector.PROTOCOL_PRIVATE, "", 0);

JMXConnector connector = JMXConnectorFactory.newJMXConnector(url, env);

            </programlisting>

          </example>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>

          RadConnector.PROTOCOL_ZONESBRIDGE

        </term>

        <listitem>

          <para>

            A connection to a non-global zone's local UNIX RAD instance,

            through an existing local/remote RAD connection to its global

            zone.  The name of the non-global zone is specified as the host.

            The non-global zone user is specified as the path.

          </para>

          <para>

            Expected parameters:

          </para>

          <variablelist>

            <varlistentry>

              <term>

                RadConnector.KEY_ZONESBRIDGE_MXBEAN

                (<code>com.oracle.solaris.rad.zonesbridge.IOMXBean</code>,

                required)

              </term>

              <listitem>

                <para>

                  an <code>IOMXBean</code> from an existing RAD connection to

                  the global zone, retrieved with a domain

                  "<code>com.oracle.solaris.rad.zonesbridge</code>" and a

                  "type=IO" key/value pair.

                </para>

              </listitem>

            </varlistentry>

          </variablelist>

          <example>

            <title>RadConnector.PROTOCOL_ZONESBRIDGE</title>

            <programlisting>

// Create a connection to some host

MBeanServerConnection mbsc = ...

ObjectName zioName = new ObjectName(

  "com.oracle.solaris.rad.zonesbridge", "type", "IO");

IOMXBean zio = JMX.newMXBeanProxy(mbsc, zioName, IOMXBean.class);

// The zone to connect to

String zone = "nerd-vpn";

// The non-global-zone user, or "" to connect as root

String zoneUser = "talley";

// Create a connection to the non-global zone on the connected host

JMXServiceURL zUrl = new JMXServiceURL(

    RadConnector.PROTOCOL_ZONESBRIDGE, zone, 0, "/" + zoneUser);

Map<String, Object> env = new HashMap<String, Object>();

env.put(RadConnector.KEY_ZONESBRIDGE_MXBEAN, zio);

JMXConnector connector = JMXConnectorFactory.connect(zUrl, env);

            </programlisting>

          </example>

        </listitem>

      </varlistentry>

    </variablelist>

  </section>

  <section>

    <title>radadrgen usage</title>

    <para>

      In the Java/JMX environment, elements declared in the module

      specification are translated to Java classes and interfaces.  The tool

      that does this translation is <command>/usr/bin/radadrgen</command>:

    </para>

    <cmdsynopsis>

      <command>/usr/bin/radadrgen</command>

      <arg choice="opt">

        <option>-N</option>

      </arg>

      <arg choice="plain">

        <option>-j</option>

      </arg>

      <arg choice="plain">

        <replaceable>dir</replaceable>

      </arg>

      <arg choice="opt">

        <option>-i</option>

      </arg>

      <arg choice="plain">

        <replaceable>spec.xml</replaceable>

      </arg>

    </cmdsynopsis>

    <para>

      The Java classes and interfaces generated by <command>radadrgen</command>

      are as follows:

    </para>

    <informaltable>

      <tgroup cols='3'>

        <thead>

          <row><entry>Element</entry><entry><command>radadrgen</command>-generated class</entry><entry>Description</entry></row>

        </thead>

        <tbody>

          <row>

            <entry><code>&lt;interface> </code></entry>

	    <entry><emphasis>package.interface</emphasis>MXBean</entry>

            <entry><code>MXBean</code> interface, implemented by object returned

            by the RAD server</entry>

          </row>

          <row>

            <entry><code>&lt;struct></code></entry>

	    <entry><emphasis>package.struct</emphasis></entry>

            <entry>struct interface</entry>

          </row>

          <row>

            <entry></entry>

	    <entry><emphasis>package.struct</emphasis>Impl</entry>

            <entry>struct implementation (if <option>-i</option> is

            used)</entry>

          </row>

          <row>

            <entry><code>&lt;union></code></entry>

	    <entry><emphasis>package.union</emphasis></entry>

            <entry>union interface</entry>

          </row>

          <row>

            <entry></entry>

            <entry>union implementation</entry>

          </row>

          <row>

            <entry><code>&lt;enum></code></entry>

            <entry><emphasis>package.enum</emphasis></entry>

	    <entry>enum class</entry>

          </row>

        </tbody>

      </tgroup>

    </informaltable>

    <para>

      ...where <emphasis>package</emphasis> is determined from the

      <code>&lt;api&gt;</code> name or a supplied 

      <link linkend="adr-idl.pragmas">pragma</link>.  

      See the section on <link linkend="best-practices.naming.object">object

      naming</link> for details.

    </para>

    <section>

      <title>Enums</title>

      <para>

        For example, given the RAD module specification

        <code>example.xml</code>:

      </para>

      <programlisting><![CDATA[

<api xmlns="http://xmlns.oracle.com/radadr"

  name="com.example.foo">

  <enum name="Color">

    <value name="Red" />

    <value name="Green" />

    <value name="Blue" />

  </enum>

  ...

</api>

]]></programlisting>

      <para>

        Calling:

      </para>

      <programlisting>

/usr/bin/radadrgen -j <emphasis>dir</emphasis> example.xml</programlisting>

      <para>

        ...generates a native Java enum class:

      </para>

      <programlisting><![CDATA[

package com.example.foo;

public enum Color {

    Red,

    Green,

    Blue,

}

]]></programlisting>

    </section>

    <section>

      <title>Structured types</title>

      <para>

        Adding a <code>&lt;struct></code> to the module API:

      </para>

      <programlisting><![CDATA[

<struct name="Person">

  <field type="string" name="name" />

  <field type="integer" name="age" />

  <field typeref="Color" name="favoriteColor" />

</struct>

]]></programlisting>

      <para>

        ...produces a Java interface that models the structured type:

      </para>

      <programlisting><![CDATA[

package com.example.foo;

public interface Person {

    String getName();

    int getAge();

    Color getFavoriteColor();

}

]]></programlisting>

      <para>

        If the <option>-i</option> is also passed to

        <command>radadrgen</command>, an implementation of the

        <code>Person</code> interface is also generated:

      </para>

      <programlisting><![CDATA[

package com.example.foo;

public class PersonImpl implements Person {

    private String name_;

    private int age_;

    private Color favoriteColor_;

    public PersonImpl() {

    }

    public PersonImpl(String name, int age, Color favoriteColor) {

        name_ = name;

        age_ = age;

        favoriteColor_ = favoriteColor;

    }

    public String getName() {

        return name_;

    }

    public int getAge() {

        return age_;

    }

    public Color getFavoriteColor() {

        return favoriteColor_;

    }

    public void setName(String arg) {

        name_ = arg;

    }