<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
<!--ArborText, Inc., 1988-1999, v.4002-->
<!ENTITY metainfo SYSTEM "metainfo.sgm">
<!ENTITY SectDesc "User Commands">
<!ENTITY options-common SYSTEM "options-common.sgm">
<!ENTITY synopsis-common SYSTEM "synopsis-common.sgm">
<!ENTITY sjsas "Sun Java System Application Server">
<!ENTITY % commonents SYSTEM "smancommon.ent">
%commonents;
<!ENTITY % booktitles SYSTEM "booktitles.ent">
%booktitles;
<!ENTITY Dash "&ndash;">
]>
<?Pub UDT _bookmark _target>
<?Pub Inc>
<refentry id="create-mbean-1">
<refmeta><refentrytitle>create-mbean</refentrytitle><manvolnum>1</manvolnum>&metainfo;
</refmeta>
<refnamediv><indexterm><primary sortas="create-mbean">create-mbean &mdash;creates
and registers a custom MBean.</primary></indexterm><indexterm><primary sortas="creates and registers a custom MBean">
creates and registers a custom MBean &mdash; create-mbean</primary></indexterm>
<refname>create-mbean </refname><refpurpose>creates and registers a custom
MBean. </refpurpose></refnamediv>
<refsynopsisdiv><title>&synp-tt;</title>
<cmdsynopsis><command>create-mbean</command>&synopsis-common;
<arg choice="opt">&Dash;&Dash;name <replaceable>name</replaceable></arg><arg
choice="opt">&Dash;&Dash;objectname <replaceable>objectname</replaceable></arg>
<arg choice="opt">&Dash;&Dash;name <replaceable>name</replaceable></arg><arg
choice="opt">&Dash;-target=<replaceable>server</replaceable> </arg><arg><option
role="nodash">&Dash;&Dash;attributes (<replaceable>name</replaceable>=<replaceable>
value</replaceable>)[:<replaceable>name</replaceable>=<replaceable>value</replaceable>]*
</option></arg><arg choice="plain"><replaceable>implementation-class-name
</replaceable></arg>
</cmdsynopsis></refsynopsisdiv>
<refsect1><title>&desc-tt;</title>
<para>Creates and registers a custom MBean. If the target <literal>MBeanServer
</literal> is not running, the MBean is not registered.</para>
<para>This command is supported in remote mode only.</para>
</refsect1>
<refsect1><title>&opts-tt;</title>
<para>If an option has a short option name, then the short option precedes
the long option name. Short options have one dash whereas long options have
two dashes.</para>
<variablelist termlength="medium">&options-common;
<varlistentry><term><option role="nodash">--name</option></term><listitem>
<para>Specifies the name of the MBean definition. It should be unique for
a given domain as the namespace for MBeans is shared with that for Java EE
applications and modules. Therefore, you should not use the name of a deployed
enterprise application for creating an MBean. The default name is the MBean's
implementation class name.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">--objectname</option></term><listitem>
<para>Specifies the <literal>javax.management.ObjectName</literal> of the
MBean. The <literal>ObjectName</literal> must be unique within the target
specified, as is the case with the name of the MBean. The uniqueness is required
because at runtime the MBeans are registered with their <literal>ObjectName
</literal> and not names. The default ObjectName is of the format: <literal>
user:type=<replaceable>implementation-class-name</replaceable>,name=<replaceable>
implementation-class-name</replaceable></literal>. The <literal>user</literal>
is the name of the JMX Domain where these MBeans will be registered. No other
JMX domain name is allowed. </para>
<para>This is the <literal>ObjectName</literal> that will be stored in the
Application Server domain's configuration. At runtime though, when the MBean
is registered in the MBeanServer, an identifying property, <literal>server=<replaceable>
name_of_the_target_server_instance</replaceable></literal> is inserted in
the <literal>ObjectName</literal>.</para>
<para>This property is not persisted. It is a runtime artifact only.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">--target</option></term><listitem>
<para>Specify the ID of the server where the MBean will be registered. Defaults
to the name of the Domain Administration Server (DAS).</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">--attributes</option></term><listitem>
<para> Specifies the names and values of the attributes for the initialization
of the MBean.</para>
<para>Specifies the names and values of the attributes that the MBean should
be initialized with. The attributes are specified in the format, <literal>
name1=value1:name2=value2:...</literal> The types of these attributes must
be simple Java Types. such as primitive data types and their wrapper classes.
In general, an attribute of the MBean that could be initialized this way should
have a constructor that accepts a <literal>java.lang.String</literal>. The
data type of the attributes is found from the <literal>MBeanInfo</literal>
of the MBean. Once initialized, these attributes are available for modification
later. These attributes loosely define the metadata of the MBean.</para>
</listitem></varlistentry>
</variablelist></refsect1>
<refsect1><title>&oper-tt;</title>
<variablelist termlength="medium">
<varlistentry><term><replaceable>implementation-class-name</replaceable></term>
<listitem><para>Specifies fully qualified name of the MBean's implementation
classname. The class should have a default constructor. In case of a Standard
MBean, it should be the name of the class that implements the Standard MBean
interface. The classes and interfaces that this MBean depends upon should
be available to the server. If they are part of the server's classpath, they
will be loaded by the server. </para>
<para>If a new MBean needs to be created while the domain administration server
is running, copy all the required classes to <literal><replaceable>appserver_install_dir
</replaceable>/<replaceable>domains_dir</replaceable>/applications/mbeans
</literal> with the proper package structure. The classes will then be dynamically
loaded. It is important to note that the MBean classes will be loaded only
from this location if they are not loaded from the server's classpath. </para>
<para>Once the MBean is created successfully, when the target server is running,
the MBean definition is persisted in the server's configuration and an instance
of the MBean is registered in the <literal>MBeanServer</literal> available
in the server's runtime. Such an MBean can then be browsed using a standard
JMX Console like JConsole.</para>
</listitem></varlistentry>
</variablelist></refsect1>
<refsect1><title>&exam-tt;</title>
<example>
<title>Using create-mbean example 1</title>
<screen><userinput>create-mbean --user admin --passwordfile filename.txt com.sun.example.Foo
</userinput></screen>
<para>This example creates an MBean definition and registers it in the runtime
of the domain administration server. The name of the MBean is <literal>com.example.Foo
</literal>, the <literal>ObjectName</literal> of the MBean is <literal>user:type=com.example.Foo,name=com.sun.example.Foo,server=server
</literal>. The attributes of the MBean will assume the values dictated by
the default constructor. </para>
</example>
<example>
<title>Using create-mbean example 2</title>
<screen><userinput>create-mbean --user admin --passwordfile filename.txt --objectname
"user:type=file,name=students.log" --name file1 --target --attributes 
Location=Root:Level=01 cluster1 com.example.Bar

</userinput></screen>
<para>This example assumes that there is a target with name <literal>cluster1
</literal>, comprised of server instances server1, server2). Clusters are
available only in Enterprise Edition of Application Server. </para>
<para>It creates an MBean definition with name <literal>file1</literal>, <literal>
ObjectName</literal> <literal>user:type=file,name=students.log</literal> (in
the configuration). The runtime MBean is registered in the default <literal>
MBeanServer</literal> in both <literal>server1</literal> and <literal>server2
</literal>. The <literal>ObjectNames</literal> of the registered MBeans would
be <literal>user:type=file,name=students.log,server=server1</literal> and <literal>
user:type=file,name=students.log,server=server2</literal> respectively. The
attributes named <literal>Location</literal> and <literal>Level</literal>
in the MBean would be initialized to <literal>Root</literal> and <literal>
01</literal> respectively. The data-type of the attributes is derived from <literal>
MBeanInfo</literal>. The MBeans will be available during runtime only if <literal>
server1</literal> and <literal>server2</literal> are running.</para>
</example>
</refsect1>
<refsect1><title>&exit-tt;</title>
<variablelist termlength="medium"><?Pub Caret>
<varlistentry><term>0</term><listitem><para> command executed successfully
</para>
<para> </para>
</listitem></varlistentry>
<varlistentry><term>1</term><listitem><para>error in executing the command
</para>
</listitem></varlistentry>
</variablelist></refsect1>
<refsect1><title>&also-tt;</title>
<para><link linkend="delete-mbean-1"><citerefentry><refentrytitle>delete-mbean
</refentrytitle><manvolnum>1</manvolnum></citerefentry></link></para>
<para><link linkend="list-mbeans-1"><citerefentry><refentrytitle>list-mbeans
</refentrytitle><manvolnum>1</manvolnum></citerefentry></link></para>
</refsect1>
</refentry>
<?Pub *0000009372>
