<!--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="list-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="">
<!-- @(#)list.1 1.12 07/06/01 SMI; -->
<refmeta><refentrytitle>list</refentrytitle><manvolnum>1</manvolnum>
<refmiscinfo class="date">3 OCt 2008</refmiscinfo>
<refmiscinfo class="sectdesc">&man1;</refmiscinfo>
<refmiscinfo class="software">&software;</refmiscinfo>
<refmiscinfo class="arch">generic</refmiscinfo>
<refmiscinfo class="copyright">Copyright (c) 2008, Sun Microsystems, Inc.
All Rights Reserved</refmiscinfo>
</refmeta>
<refnamediv><indexterm><primary>list</primary></indexterm><indexterm><primary>lists
the configurable elements</primary></indexterm>
<refname>list</refname><refpurpose>lists the configurable elements</refpurpose>
</refnamediv>
<refsynopsisdiv><title></title>
<synopsis><command>list</command> &synopsis-common; [<option role="double-dash">monitor
</option>=<replaceable>false</replaceable>]
 [<replaceable>dotted_parent_attribute_name</replaceable>]</synopsis>
</refsynopsisdiv>
<refsect1 role="description"><title></title>
<para>Lists the configurable element. On Solaris, quotes are needed when executing
commands with * as the option value or operand.</para>
<para>The dotted notation follows these guidelines:</para>
<itemizedlist>
<listitem><para>Any <command>list</command> command that has a dotted name
that is not followed by a wildcard (*) will get, as its result, the current
node's immediate children. For example, <command>list</command> <option>-monitor</option> <command>
server</command> lists all immediate children belonging to the server node.</para>
</listitem>
<listitem><para>Any <command>list</command> command that has a dotted name
followed by a wildcard(*) will get, as its result, a hierarchical tree of
children nodes from the current node. For example, <command>list</command> <option>
-monitor</option> <command>server.applications.*</command> will list all children
of applications and their subsequent child nodes and so on.</para></listitem>
<listitem><para>Any <command>list</command> command that has a dotted name
preceded or followed by a wildcard (*) of the form <emphasis>*dotted name</emphasis> or <emphasis>
dotted * name</emphasis> or <emphasis>dotted name*</emphasis> will get, as
its result, all nodes and their children matching the regular expression created
by the provided matching pattern.</para></listitem>
</itemizedlist>
<para>A dotted name uses the &ldquo;<literal>.</literal>&rdquo; (period) as
a delimiter to separate the parts of a complete name. This is similar to how
the &ldquo;<literal>/</literal>&rdquo; character is used to delimit the levels
in the absolute path name of a file in the UNIX file system. The following
rules apply while forming the dotted names accepted by the <command>get</command>, <command>
set</command> and <command>list</command> commands. Note that a specific command
has some additional semantics applied.</para>
<itemizedlist>
<listitem><para> A <literal>.</literal> (period) always separates two sequential
parts of the name.</para></listitem>
<listitem><para>A part of the name usually identifies a subsystem and/or its
specific instance. For example: web-container, log-service, thread-pool-1
etc.</para></listitem>
<listitem><para>If any part of the name itself contains a <literal>.</literal> (period),
then it must be escaped with a leading <literal>\</literal> (backslash) so
that the &ldquo;<literal>.</literal>&rdquo; does not act like a delimiter.</para>
</listitem>
<listitem><para>An <literal>*</literal> (asterisk) can be used anywhere in
the dotted name and it acts like the wildcard character in regular expressions.
Additionally, an <literal>*</literal> can collapse all the parts of the dotted
name. Long dotted name like "<classname>this.is.really.long.hierarchy</classname>"
can be abbreviated to "<classname>th*.hierarchy</classname>". But note that
the <literal>.</literal> always delimits the parts of the name.</para>
</listitem>
<listitem><para>The top level switch for any dotted name is <option>monitor</option> or <option>
m</option> that is separately specified on a given command line. The presence
or lack of this switch implies the selection of one of the two hierarchies
for appserver management: monitoring and configuration.</para></listitem>
<listitem><para>If you happen to know the exact complete dotted name without
any wildcard character, then list and get/set have a little difference in
their semantics:</para>
<itemizedlist>
<listitem><para>The <command>list</command> command treats this complete dotted
name as the complete name of a parent node in the abstract hierarchy. Upon
providing this name to <command>list</command> command, it simply returns
the names of the immediate children at that level. For example, <command>list
server.applications.web-module</command> will list all the web modules deployed
to the domain or the default server.</para></listitem>
<listitem><para>The<command> get</command> and <command>set</command> commands
treat this complete dotted name as the fully qualified name of the attribute
of a node (whose dotted name itself is the name that you get when you remove
the last part of this dotted name) and it gets/sets the value of that attribute.
This is true if such an attribute exists. You will never start with this case
because in order to find out the names of attributes of a particular node
in the hierarchy, you must use the wildcard character <literal>*</literal>.
For example, <command>server.applications.web-module.JSPWiki.context-root</command> will
return the context-root of the web-application deployed to the domain or default
server.</para></listitem>
</itemizedlist>
</listitem>
<listitem><para><classname>server</classname>(usually the first part of the
complete dotted name) can be replaced with the name of a particular server
instance of interest (e.g., <classname>server1</classname>) and you'll get
the information of that server instance, remaining part of the dotted name
remaining the same. Note that the dotted names that are available in such
other server instances are those from the monitoring hierarchy because these
server instances don't have a way to expose the configuration hierarchy.</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1 role="options"><title></title>
<variablelist termlength="medium">&options-common;
<varlistentry><term><option>-monitor</option></term>
<listitem><para>defaults to false; if set to false, the configurable attribute
values are returned. If set to true, the monitorable attribute values are
returned.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="operands"><title></title>
<variablelist termlength="medium">
<varlistentry><term><replaceable>dotted_parent_element_name</replaceable></term>
<listitem><para>configurable or monitorable element name.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="examples"><title></title>
<example><title>Using <command>list</command> to view all dotted-name prefixes</title>
<screen>asadmin> <userinput>list --user admin --passwordfile password.txt 
--port 5001 "*"</userinput>
server
server.admin-service
server.admin-service.das-config
server.application-ref.MEjbApp
server.application-ref.__ejb_container_timer_app
server.application-ref.adminapp
server.application-ref.admingui
server.application-ref.com_sun_web_ui
server.applications
server.applications.j2ee-application.MEjbApp
server.applications.j2ee-application.__ejb_container_timer_app
server.applications.web-module.adminapp
server.applications.web-module.admingui
server.applications.web-module.com_sun_web_ui
server.ejb-container
server.http-service
server.http-service.http-listener.admin-listener
server.http-service.http-listener.http-listener-1
server.http-service.http-listener.http-listener-2
server.iiop-service
server.iiop-service.iiop-listener.SSL
server.iiop-service.iiop-listener.SSL.ssl
server.iiop-service.iiop-listener.SSL_MUTUALAUTH
server.iiop-service.iiop-listener.SSL_MUTUALAUTH.ssl
server.iiop-service.iiop-listener.orb-listener-1
server.iiop-service.orb
server.java-config
server.jms-service
server.jms-service.jms-host.default_JMS_host
server.log-service
server.log-service.module-log-levels
server.mdb-container
server.monitoring-service
server.monitoring-service.module-monitoring-levels
server.resource-ref.jdbc/PointBase
server.resource-ref.jdbc/__TimerPool
server.resources
server.resources.jdbc-connection-pool.PointBasePool
server.resources.jdbc-connection-pool.__TimerPool
server.resources.jdbc-resource.jdbc/PointBase
server.resources.jdbc-resource.jdbc/__TimerPool
server.security-service
server.security-service.audit-module.default
server.security-service.auth-realm.certificate
server.security-service.auth-realm.file
server.security-service.jacc-provider.default
server.thread-pools
server.thread-pools.thread-pool.thread-pool-1
server.transaction-service
server.virtual-server.__asadmin
server.virtual-server.server
server.web-container</screen>
</example>
<example><title>Using <command>list</command> for an application</title>
<screen>asadmin> <userinput>list --user admin --passwordfile password.txt 
--host localhost --port 4848 server.applications.j2ee-application</userinput>
server.applications.j2ee-application.MEjbApp
server.applications.j2ee-application._ejb_container_timer_app
server.applications.j2ee-application.stateless-simple</screen>
</example>
<example><title>Using <command>list</command> for a web module</title>
<screen>asadmin> <userinput>list --user admin --passwordfile password.txt 
--host localhost --port 4848 server.applications.web-module</userinput>
server.applications.web-module.adminapp
server.applications.web-module.adminguip
server.applications.web-module.com_sun_web_ui</screen>
</example>
</refsect1>
<refsect1 role="examples"><title></title>
<para>The <command>list</command> command is the progenitor of navigational
capabilities of these three commands. If you want to <command>set</command> or <command>
get</command> attributes of a particular subsystem, you must know its dotted
name. The <command>list</command> command is the one which can guide you to
find the dotted name of that subsystem. For example, to find out the modified
date (attribute) of a particular file in a large file system that starts with <literal>
/</literal>. First you must find out the location of that file in the file
system, and then look at its attributes. Therefor, two of the first commands
to understand the hierarchies in appserver are: <command>* list "*"</command> and <command>
* list * </command><option role="double-dash">monitor</option>. </para>
<para>A part of the sorted output of the <command>list "*"</command>command
is typically of the following form:</para>
<example><title>Listing all dotted names</title>
<screen>asadmin> <userinput>list "*"</userinput>
default-config.sip-service.sip-protocol.sip-timers
default-config.thread-pools
default-config.thread-pools.thread-pool.thread-pool-1
default-config.transaction-service
default-config.web-container
default-config.web-container-availability
domain
domain.clusters
domain.configs
domain.converged-lb-configs
domain.converged-lb-configs.converged-lb-config-1

</screen>
</example>
<note><para>The <literal>web-container-availability</literal> node and the <literal>
ejb-container-availability</literal> do not appear under the <literal>availability-service
</literal> node. These dotted names can be accessed as follows:</para><para><literal>
default-config.web-container-availability</literal></para><para><literal>default-config.web-container-availability
</literal></para><para>The <literal>jms-availability</literal> child node
appears under the <literal>availability-service</literal> node as follows:</para>
<para><literal>default-config.availability-service.jms-availability</literal></para>
</note>
<para>The output of the<command>list</command> command is a list of dotted
names representing individual components and subsystems. Every component or
subsystem is capable of having zero or more attributes that can be read and
modified.</para>
<para>With the<command>list</command> command you can drill down through the
hierarchy in a particular branch of interest. For example, if you want to
find the configuration of the <command>http-listener</command> of the domain
(the default server, whose ID is "<classname>server</classname>"). Here is
how you could proceed on a UNIX terminal:</para>
<example><title>Listing all dotted names containing http and listener</title>
<screen><userinput>asadmin list "*"|grep http|grep listener</userinput>
default-cluster-config.http-service.http-listener.http-listener-1
default-cluster-config.http-service.http-listener.http-listener-2
default-cluster-config.http-service.http-listener.http-listener-2.ssl
default-cluster.http-service.http-listener.http-listener-1
default-cluster.http-service.http-listener.http-listener-2
default-cluster.http-service.http-listener.http-listener-2.ssl
default-config.http-service.http-listener.http-listener-1
default-config.http-service.http-listener.http-listener-2
default-config.http-service.http-listener.http-listener-2.ssl
server-config.http-service.http-listener.admin-listener
server-config.http-service.http-listener.http-listener-1
server-config.http-service.http-listener.http-listener-2
server-config.http-service.http-listener.http-listener-2.ssl
server.http-service.http-listener.admin-listener
server.http-service.http-listener.http-listener-1
server.http-service.http-listener.http-listener-2
server.http-service.http-listener.http-listener-2.ssl

</screen>
</example>
<para>Consequently, the <command>list</command> command is the entry point
into the navigation of the management hierarchies. Take note of the output
of the <command>list</command> command:</para><?Pub Caret>
<itemizedlist>
<listitem><para>The output lists one element per line.</para></listitem>
<listitem><para> Every element on a line is a complete-dotted-name of a management
component that is capable of having attributes. Note that none of these lines
show any kind of attributes at all.</para></listitem>
</itemizedlist>
<para>You can now use this output of the list command to find the attributes
of the default <command>http-listener</command> where the web applications
in the <filename>domain/server</filename> are deployed.</para>
<example><title>Getting the attributes of a listener</title>
<screen><userinput>asadmin get server.http-service.http-listener.http-listener-1</userinput>
server.http-service.http-listener.http-listener-1.acceptor-threads = 1
server.http-service.http-listener.http-listener-1.address = 0.0.0.0
server.http-service.http-listener.http-listener-1.blocking-enabled = false
server.http-service.http-listener.http-listener-1.default-virtual-server = server
server.http-service.http-listener.http-listener-1.enabled = true
server.http-service.http-listener.http-listener-1.external-port =
server.http-service.http-listener.http-listener-1.family = inet
server.http-service.http-listener.http-listener-1.id = http-listener-1
server.http-service.http-listener.http-listener-1.port = 51378
server.http-service.http-listener.http-listener-1.property.accesslog 
= ${com.sun.aas.instanceRoot}/logs/access
server.http-service.http-listener.http-listener-1.property.proxiedProtocols = ws/tcp
server.http-service.http-listener.http-listener-1.redirect-port =
server.http-service.http-listener.http-listener-1.security-enabled = false
server.http-service.http-listener.http-listener-1.server-name =
server.http-service.http-listener.http-listener-1.xpowered-by = true

</screen>
</example>
</refsect1>
<refsect1 role="examples"><title> </title>
<example><title>Exploring JVM attributes</title>
<para>You can use the following set of list and get commands to explore JVM
attributes. </para>
<screen><userinput>asadmin list server*|grep monitoring </userinput>
server-config.monitoring-service
server-config.monitoring-service.module-monitoring-levels
server.monitoring-service
server.monitoring-service.module-monitoring-levels</screen>
<para>Note that this is the <command>list</command> command. It only shows
the hierarchy, nothing else. Using the '|' and "grep" narrows down the search
effectively. Now, you can choose <classname>server.monitoring-service</classname> to
set the attributes of various attributes that can be monitored.</para>
<para>This is the configuration data because this setting will be persisted
to the server's configuration store.</para>
<screen><userinput>asadmin get server.monitoring-service.* </userinput></screen>
<para>You can try the number of attributes that are presently available with
monitoring service. Here is the output: </para>
<para>No matches resulted from the wildcard expression. This is because this
fully dotted name does not have any attributes at all. Logically, you try
the next one and that is: <command>server.monitoring-service.module-monitoring-levels
</command>. Again, use the wildcard character to get ALL the attributes of
a particular component.</para>
<screen><userinput>asadmin get server.monitoring-service.module-monitoring-levels.*
</userinput>
server.monitoring-service.module-monitoring-levels.
connector-connection-pool = OFF 
server.monitoring-service.module-monitoring-levels.
connector-service = OFF 
server.monitoring-service.module-monitoring-levels.
ejb-container = OFF 
server.monitoring-service.module-monitoring-levels.
http-service = OFF 
server.monitoring-service.module-monitoring-levels.
jdbc-connection-pool = OFF 
server.monitoring-service.module-monitoring-levels.
jms-service = OFF 
server.monitoring-service.module-monitoring-levels.
jvm = OFF 
server.monitoring-service.module-monitoring-levels.
orb = OFF 
server.monitoring-service.module-monitoring-levels.
thread-pool = OFF 
server.monitoring-service.module-monitoring-levels.
transaction-service = OFF 
server.monitoring-service.module-monitoring-levels.
web-container = OFF </screen>
<para>The JVM monitoring is at a level OFF. It must be changed in order to
make the JVM monitoring information available. The other valid values for
all the monitoring level are: LOW and HIGH. use the <command>set</command> command
to set the value appropriately.</para>
<screen><userinput>asadmin set server.monitoring-service.module-monitoring-levels.jvm=HIGH
</userinput>
erver.monitoring-service.module-monitoring-levels.jvm = HIGH</screen>
<para>Now, the JVM information can be obtained using the <command>get</command> command
and monitoring switch. But remember , when you switch to the monitoring hierarchy,
start with the <command>list</command> command again. </para>
<screen><userinput>asadmin list --monitor * | grep jvm</userinput>
server.jvm 
server.jvm.class-loading-system 
server.jvm.compilation-system 
server.jvm.garbage-collectors 
server.jvm.garbage-collectors.Copy 
server.jvm.garbage-collectors.MarkSweepCompact
server.jvm.memory server.jvm.operating-system 
server.jvm.runtime server.jvm.thread-system 
server.jvm.thread-system.thread-1 
. . .
server.jvm.thread-system.thread-793823 
server.jvm.thread-system.thread-793824 
server.jvm.thread-system.thread-793825 
server.jvm.thread-system.thread-793826 
server.jvm.thread-system.thread-793827 
server.jvm.thread-system.thread-9</screen>
<para>Note that now you are interested in the attributes of a particular leaf
node. Thus the command is <command>get</command> not <command>list</command>.</para>
<screen><userinput>asadmin get -m  server.jvm.class-loading-system.*</userinput>
server.jvm.class-loading-system.dotted-name = server.jvm.class-loading-system 
server.jvm.class-loading-system.loadedclasscount-count = 7328 
server.jvm.class-loading-system.loadedclasscount-description = 
No Description was available 
server.jvm.class-loading-system.loadedclasscount-lastsampletime = 1133819508973 
server.jvm.class-loading-system.loadedclasscount-name = LoadedClassCount? 
server.jvm.class-loading-system.loadedclasscount-starttime = 1133819131268 
server.jvm.class-loading-system.loadedclasscount-unit = count 
server.jvm.class-loading-system.totalloadedclasscount-count = 10285 
server.jvm.class-loading-system.totalloadedclasscount-description 
= No Description was available 
server.jvm.class-loading-system.totalloadedclasscount-lastsampletime = 1133819508972 
server.jvm.class-loading-system.totalloadedclasscount-name = TotalLoadedClassCount? 
server.jvm.class-loading-system.totalloadedclasscount-starttime = 1133819131268 
server.jvm.class-loading-system.totalloadedclasscount-unit = count 
server.jvm.class-loading-system.unloadedclasscount-count = 2957 
server.jvm.class-loading-system.unloadedclasscount-description = 
No Description was available 
server.jvm.class-loading-system.unloadedclasscount-lastsampletime = 1133819508973 
server.jvm.class-loading-system.unloadedclasscount-name = UnloadedClassCount? 
server.jvm.class-loading-system.unloadedclasscount-starttime = 1133819131268 
server.jvm.class-loading-system.unloadedclasscount-unit = count</screen>
</example>
<para>You can see that 10285 is the total number of classes loaded by the
Virtual Machine. Whereas, 2957 is number of classes unloaded, since it was
started.  Similarly, you can explore attributes of the other subsystems as
well.</para>
</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="get-1">get(1)</olink>, <olink
targetdoc="asrefman" targetptr="set-1">set(1)</olink></para>
</refsect1>
</refentry>
<?Pub *0000022311 0>
