<!--Arbortext, Inc., 1988-2008, v.4002-->
<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD SolBook 3.5//EN" [
<!ENTITY options-common SYSTEM "options-common.sgm">
<!ENTITY synopsis-common SYSTEM "synopsis-common.sgm">
<!ENTITY % commonents SYSTEM "common.ent">
%commonents;
]>
<?Pub UDT _bookmark _target>
<?Pub EntList bull rArr sect>
<?Pub Inc>
<refentry id="create-mbean-1"><?Pub Tag atict:info tracking="off" ref="2"><?Pub Tag
atict:user user="hl34125" fullname=""><?Pub Tag atict:user user="pmdavies"
fullname=""><?Pub Tag atict:user user="ah95648" fullname="">
<!-- @(#)create-mbean.1 1.12 07/07/26 SMI; -->
<refmeta><refentrytitle>create-mbean</refentrytitle><manvolnum>1</manvolnum>
<refmiscinfo class="date">13 Jul 2007</refmiscinfo>
<refmiscinfo class="sectdesc">&man1;</refmiscinfo>
<refmiscinfo class="software">&software;</refmiscinfo>
<refmiscinfo class="arch">generic</refmiscinfo>
<refmiscinfo class="copyright">Copyright (c) 2007, Sun Microsystems, Inc.
All Rights Reserved</refmiscinfo>
</refmeta>
<refnamediv><indexterm><primary>create-mbean</primary></indexterm><indexterm>
<primary>creates and registers a custom MBean</primary></indexterm>
<refname>create-mbean </refname><refpurpose>creates and registers a custom
MBean</refpurpose></refnamediv>
<refsynopsisdiv><title></title>
<synopsis><command>create-mbean</command> &synopsis-common; [<option
role="double-dash">name</option> <replaceable>name</replaceable>]
 [<option role="double-dash">objectname</option> <replaceable>objectname</replaceable>] [<option
role="double-dash">name</option> <replaceable>name</replaceable>]
 [&ndash;-target=<replaceable>server</replaceable> ] [<option role="double-dash">
attributes</option> (<replaceable>name</replaceable>=<replaceable>value</replaceable>)[:<replaceable>
name</replaceable>=<replaceable>value</replaceable>]*]
 <replaceable>implementation-class-name</replaceable></synopsis>
</refsynopsisdiv>
<refsect1 role="description"><title></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 role="options"><title></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="wholeline">&options-common;
<varlistentry><term><option role="double-dash">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="double-dash">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<?Pub
Caret> 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="double-dash">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="double-dash">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 role="operands"><title></title>
<variablelist termlength="wholeline">
<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 role="examples"><title></title>
<example><title>Using create-mbean example 1</title>
<screen>asadmin> <userinput>create-mbean --user admin --passwordfile filename.txt 
--objectname "user:type=com.example.Foo" 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>asadmin> <userinput>create-mbean --user admin --passwordfile filename.txt --objectname
"user:type=file,name=students.log" --name file1 --target cluster1 com.example.Bar 
--attributes Location=Root:Level=01 </userinput></screen>
<para>This example assumes that there is a target with name <literal>cluster1</literal>,
comprised of server instances server1, server2). </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 role="exit-status"><title></title>
<variablelist termlength="medium">
<varlistentry><term>0</term>
<listitem><para> command executed successfully</para>
</listitem>
</varlistentry>
<varlistentry><term>1</term>
<listitem><para>error in executing the command</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="see-also"><title></title>
<para><olink targetdoc="asrefman" targetptr="delete-mbean-1">delete-mbean(1)</olink></para>
<para><olink targetdoc="asrefman" targetptr="list-mbeans-1">list-mbeans(1)</olink></para>
</refsect1>
</refentry>
