
Administration Commands                           create-mbean(1)

NAME
     create-mbean  - creates and registers a custom MBean

SYNOPSIS
     create-mbean
     [--terse={true|false}][ --echo={true|false} ]
     [ --interactive={true|false} ] [ --host  host]
     [--port port] [--secure| -s ] [ --user  admin_user]
     [--passwordfile filename] [--help]
     [ --name  name]
     [--objectname objectname] [--name name]
     [--target=server ] [--attributes (name=value)[:name=value]*]
     implementation-class-name

DESCRIPTION
     Creates and registers a custom MBean. If the  target  MBean-
     Server is not running, the MBean is not registered.

     This command is supported in remote mode only.

OPTIONS
     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.

     -t --terse

         Indicates that any output data  must  be  very  concise,
         typically avoiding human-friendly sentences and favoring
         well-formatted data for consumption by a script. Default
         is false.

     -e --echo
         Setting to true will echo the command line statement  on
         the standard output. Default is false.

     -I --interactive

         If set to true (default),  only  the  required  password
         options are prompted.

     -H --host
         The machine name where the domain administration  server
         is running. The default value is localhost.

Java EE 5           Last change: 13 Jul 2007                    1

Administration Commands                           create-mbean(1)

     -p --port

         The HTTP/S port for administration. This is the port  to
         which  you  should point your browser in order to manage
         the domain. For example, http://localhost:4848.

         The default port number is 4848.

     -s --secure
         If set to true, uses SSL/TLS  to  communicate  with  the
         domain administration server.

     -u --user

         The authorized domain administration server  administra-
         tive username.

         If you have authenticated to a domain using the  asadmin
         login  command,  then  you  need  not specify the --user
         option  on  subsequent  operations  to  this  particular
         domain.

     --passwordfile
         The --passwordfile option specifies the name,  including
         the full path, of a file containing the password entries
         in a specific format. The entry for  the  password  must
         have  the AS_ADMIN_ prefix followed by the password name
         in uppercase letters.

         For example, to specify the domain administration server
         password,  use  an  entry  with  the  following  format:
         AS_ADMIN_PASSWORD=password, where password is the actual
         administrator  password.  Other  passwords  that  can be
         specified        include        AS_ADMIN_MAPPEDPASSWORD,
         AS_ADMIN_USERPASSWORD, and AS_ADMIN_ALIASPASSWORD.

         All remote commands must specify the admin  password  to
         authenticate to the domain administration server, either
         through --passwordfile or  asadmin  login,  or  interac-
         tively  on the command prompt. The asadmin login command
         can be used only to  specify  the  admin  password.  For
         other  passwords, that must be specified for remote com-
         mands, use the --passwordfile or enter them at the  com-
         mand prompt.

         If you have authenticated to a domain using the  asadmin
         login command, then you need not specify the admin pass-
         word through the  --passwordfile  option  on  subsequent
         operations  to  this particular domain. However, this is

Java EE 5           Last change: 13 Jul 2007                    2

Administration Commands                           create-mbean(1)

         applicable only to AS_ADMIN_PASSWORD  option.  You  will
         still  need to provide the other passwords, for example,
         AS_ADMIN_USERPASSWORD, as and when required  by  indivi-
         dual commands, such as update-file-user.

         For security reasons, passwords specified as an environ-
         ment variable will not be read by asadmin.

         The  default  value   for   AS_ADMIN_MASTERPASSWORD   is
         changeit.

     --help

         Displays the help text for the command.

     --name
         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.

     --objectname

         Specifies the javax.management.ObjectName of the  MBean.
         The  ObjectName  must be unique within the target speci-
         fied, as is the case with the name  of  the  MBean.  The
         uniqueness is required because at runtime the MBeans are
         registered with their  ObjectName  and  not  names.  The
         default     ObjectName     is     of     the     format:
         user:type=implementation-class-
         name,name=implementation-class-name.  The  user  is  the
         name of the  JMX  Domain  where  these  MBeans  will  be
         registered. No other JMX domain name is allowed.

         This is the  ObjectName  that  will  be  stored  in  the
         domain's  configuration.  At  runtime  though,  when the
         MBean is registered in the MBeanServer,  an  identifying
         property,  server=name_of_the_target_server_instance  is
         inserted in the ObjectName.

         This property is not persisted. It is a runtime artifact
         only.

     --target
         Specify the ID of the server where  the  MBean  will  be
         registered.    Defaults   to  the  name  of  the  Domain

Java EE 5           Last change: 13 Jul 2007                    3

Administration Commands                           create-mbean(1)

         Administration Server (DAS).

     --attributes

          Specifies the names and values of  the  attributes  for
         the initialization of the MBean.

         Specifies the names and values of  the  attributes  that
         the MBean should be initialized with. The attributes are
         specified in the  format,  name1=value1:name2=value2:...
         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 ini-
         tialized this way should have a constructor that accepts
         a  java.lang.String.  The data type of the attributes is
         found from the MBeanInfo of the MBean. Once initialized,
         these  attributes  are available for modification later.
         These attributes loosely  define  the  metadata  of  the
         MBean.

OPERANDS
     implementation-class-name
         Specifies fully qualified name of the MBean's  implemen-
         tation  classname.  The class should have a default con-
         structor. 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.

         If a new MBean needs to  be  created  while  the  domain
         administration  server is running, copy all the required
         classes                                               to
         appserver_install_dir/domains_dir/applications/mbeans
         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.

         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  MBeanServer  available  in  the
         server's runtime. Such an  MBean  can  then  be  browsed
         using a standard JMX Console like JConsole.

EXAMPLES

Java EE 5           Last change: 13 Jul 2007                    4

Administration Commands                           create-mbean(1)

     Example 1 Using create-mbean example 1

       asadmin> create-mbean --user admin --passwordfile filename.txt
       --objectname "user:type=com.example.Foo" com.sun.example.Foo

     This example creates an MBean definition and registers it in
     the runtime of the domain administration server. The name of
     the MBean is com.example.Foo, the ObjectName of the MBean is
     user:type=com.example.Foo,name=com.sun.example.Foo,server=server.
     The attributes of the MBean will assume the values  dictated
     by the default constructor.

     Example 2 Using create-mbean example 2

       asadmin> 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

     This example assumes that there is a target with name  clus-
     ter1, comprised of server instances server1, server2).

     It creates an MBean definition with name  file1,  ObjectName
     user:type=file,name=students.log (in the configuration). The
     runtime MBean is registered in the  default  MBeanServer  in
     both server1 and server2.  The ObjectNames of the registered
     MBeans                       would                        be
     user:type=file,name=students.log,server=server1          and
     user:type=file,name=students.log,server=server2      respec-
     tively.   The  attributes  named  Location  and Level in the
     MBean would be initialized to Root and 01 respectively.  The
     data-type  of the attributes is derived from MBeanInfo.  The
     MBeans will be available during runtime only if server1  and
     server2 are running.

EXIT STATUS
     0                            command executed successfully

     1                           error in executing the command

Java EE 5           Last change: 13 Jul 2007                    5

Administration Commands                           create-mbean(1)

SEE ALSO
     delete-mbean(1)

     list-mbeans(1)

Java EE 5           Last change: 13 Jul 2007                    6

