|
Table of Contents (Status: Draft, Ready for Review,
Reviewed, ARC'ed )
1. Introduction
1.1 Project/Component Working Name
1.2 Name(s) and e-mail address of Document
Author(s)/Supplier
1.3. Date of This Document
2. Project Summary
2.1 Project Description
2.2 Risks and Assumptions
3. Problem Summary
3.1 Problem Area
3.2 Justification
4. Technical Description
4.1 Details
4.2 Bugs/RFE's
4.3 Scope
4.4 Out-of-scope
4.5 Interfaces
4.6 Documentation Impact
4.7 Configuration/administration Impact
4.8 High Availability Impact
4.9 Internationalization
4.10 Packaging
4.11 Security Impact
4.12 Compatibility
4.12 Dependencies
5. References
6. Schedule
7. Document History
1. Introduction
1.1. Project/Component Working Name
Command Line Interface for GlassFish V2/Sun Java System
Application Server 9.1.
1.2. Name(s) and e-mail address of
Document Author(s)/Supplier
Jane Young (jane.young@sun.com)
Prashanth Abbagani (prashanth.abbagani@sun.com)
Kedar Mhaswade (Kedar.Mhaswade@Sun.Com)
1.3. Date of This Document
09/01/2006.
2. Project Summary
2.1. Project Description
Admin CLI is a client side tool to administer, configure and
monitor GlassFish V2. This tool is called "asadmin"
In addition to asadmin, asant is
also considered a part of Admin CLI. asant is
an extention to Ant tool developed by the Apache Software Foundation
(see http://ant.apache.org/). asant supports additional built-in tasks
that interact with the GlassFish administration utility.
2.2. Risks and Assumptions
All of the CLI remote commands depends on backend support from
MBean and AMX API.
3. Problem Summary
3.1. Problem Area
New CLI commands will be introduced to support
the
new features and enhancements.
CLI will also be improved for better usability. These
improvements include the following:
- CLI exit code enhancement for start/stop commands.
- Deprecation of --adminuser and --adminpassword in
create-domain command.
- Improve asadmin help, at least in terms of finding a
command.
- Improve asadmin command synopsis
3.2. Justification
Since CLI is one of the tools that user will need to get
accustom to when administering and configurating GlassFish,
it's important to support the new features and enhancements from
CLI. Adding new features and enhancements in CLI will
improve Glassfish's competitive market advantage by meeting and
sometimes exceeding competitors feature sets.
4. Technical Description
4.1. Details
Additions to the
command set:
Connection
Pool Enhancements:
The dotted notation for the new
connection pool attributes are listed
below. The new attributes are underlined.
domain.resources.jdbc-connection-pool.<pool-id>.lazy-connection-association=<true|false>
domain.resources.jdbc-connection-pool.<pool-id>.lazy-connection-enlistment=<true|false>
domain.resources.jdbc-connection-pool.<pool-id>.associate-with-thread=<true|false>
domain.resources.jdbc-connection-pool.<pool-id>.match-connections=<true|false>
domain.resources.jdbc-connection-pool.<pool-id>.allow-non-component-callers=<true|false>
domain.resources.jdbc-connection-pool.<pool-id>.connection-leak-timeout-in-seconds=<timeout
value>
domain.resources.jdbc-connection-pool.<pool-id>.connection-leak-reclaim=<true|false>
domain.resources.jdbc-connection-pool.<pool-id>.connection-creation-retry-attempts=<attempt
value>
domain.resources.jdbc-connection-pool.<pool-id>.connection-creation-retry-interval-in-seconds=<interval
value>
domain.resources.jdbc-connection-pool.<pool-id>.is-connection-validation-required=<true|false>
domain.resources.jdbc-connection-pool.<pool-id>.validate-atmost-once-period-in-seconds=<value>
domain.resources.jdbc-connection-pool.<pool-id>.statement-timeout-in-seconds=<timeout
value>
domain.resources.jdbc-connection-pool.<pool-id>.max-connection-usage-count=<count>
domain.resources.jdbc-connection-pool.<pool-id>.wrap-jdbc-objects=<true|false>
Portbase
option in create-domain command
create-domain --user admin --port port_number [--terse=false] [--echo=false] [--interactive=true] [--domaindir domain_directory] [--passwordfile filename] [--portbase portbase_number] [--instanceport port_number] [--savemasterpassword=false] [--domainproperties (name=value)[:name=value]*] domain_name
A new optional option, --portbase
will be added to create-domain
command. The --portbase
option will bias all default ports with that number.
The value of the portbase will be added to a default value of all the
ports. The default values are:
Admin port = 48 (in PE)
Admin port = 49 (in EE)
Instance port = 80
JMS port = 76
IIOP port = 37
HTTPS port = 81
IIOPS port = 38
IIOP MutualAuth port =39
JMX port = 86
If portbase is 10000, then the following default ports will be used in
AppServer:
10048 for Admin Port
10080 for HTTP Instance.
10076 for JMS.
10037 for IIOP.
10081 for HTTP_SSL.
10038 for IIOP_SSL.
10039 for IIOP_MUTUALAUTH.
10086 for JMX_ADMIN.
If portbase is specified and either adminport, instanceport or
domainproperites options is also specified then fail the command
stating that the options are mutually exclusive.
If any of the ports are below 1024, then a warning message is displayed.
(See: 6378839)
New options in start-node-agent command
The start-node-agent command will have a new optional option.
This option is sycinstance. If true the start-node-agent commadn
will sync up with the server instances. The default value is
false.
(See bug: 6155765)
New monitoring command
Currently, the only way to retrieve monitoring attributes from asadmin
is using the "get -m .... <dotted-name>". The drawback of
this
is that the user will need to know the dotted-names for the
monitoring
attributes. In addition, the output format is not in
CSV so it's
difficult to import it to a spread sheet. In this release,
a new command, monitor
is introduced. This
command prints out the commonly monitored attributes on
stdout and
there is an
option to filter out elements and also capture the output to a file in
CSV.
monitor
--type monitor_type [--user
admin_user] [--port 4848] [--passwordfile file_name] [--host
localhost] [--terse=false]
[--echo=false] [--interactive=true]
[--secure|-s=true] [--filename filename] [--interval 30]
[--filter name] server
Name
|
Description
|
filename
|
save ouput to a file in
CVS format
|
interval
|
time interval in seconds
to capture monitoring attributes. If interval is zero then the
current statistic is returned. If interval is greater than 0,
then the monitoring attributes is displayed on stdout until user types
ctrl-c or 'q'. Default value is 30.
|
filter
|
filters on the specific
element(s)
|
type
|
valid values are:
httplistener, keepalive, filecache, connectionqueue, jdbcpool, jvm,
threadpool, servlet, connection, connectorpool, endpoint, entitybean,
messagedriven, statefulsession, statelesssession, httpservice,
webmodule.
|
Exit
codes for start and stop commands
Currently, when start-domain
is invoked on a domain that is "killed", the command exits with an exit code of 1. Though it
is arguable that it should be 0, some experts say that it is a sign of
robustness if it exited with 0. The SMF support to
restart domain poses a problem where if domain is abrupted killed (kill
-9...) , the service that restarts the domain will first stop the
domain (for cleanup) but since domain has already stopped, stop-domain
returns an exit code of 1 and the service that restarts the domain
fails. (See Issue: 695)
In this release, the start/stop-domain will exit with exit code of 1 if
domain has already started/stopped. This exit code will be
consistent in all the lifecycle commands except for
cluster. Please see bug: 6505272 for
why exit code for start/stop-cluster will not be impacted by this
change.
Though changing the
exit code is an interface change and scripts that depend on this will
be impacted but this is the right thing to do and it's better to change
this sooner than later. The table below summarizes the
exit code for the start and stop
commands.
Commands
|
Exit Code: 0
|
Exit Code: 1
|
start-domain
start-node-agent
start-instance |
- If start successfully
- If already started
|
- If unable to start
- If it doesn't exist
|
stop-domain
stop-node-agent
stop-instance |
- If stop successfully
- If already stopped
|
- If unable to stop
- If it doesn't exist
|
Deprecation
of --adminuser and AS_ADMIN_ADMINPASSWORD in
create-domain command.
In
create-domain command adminuser is
commonly confused with user option.
And AS_ADMIN_ADMINPASSWORD in the
passwordfile is commonly confused with AS_ADMIN_PASSWORD. In this
release, adminuser
and AS_ADMIN_ADMINPASSWORD are deprecated and user and
AS_ADMIN_PASSWORD are added in create-domain command.
To
be backward
compatible, create-domain
will accept adminuser and
AS_ADMIN_ADMINPASSWORD in place of user and
AS_ADMIN_PASSWORD.
If options: adminuser and user are
specified on the command line and AS_ADMIN_ADMINPASSWORD and
AS_ADMIN_PASSWORD in passwordfile, then adminuser and
AS_ADMIN_ADMINPASSWORD
will take precedence.
Improve
asadmin help to find a
command
The help command will be enhanced
to display the closest matched
command names if the manpage and usage-text for the command do not
exist. For
example:
asadmin help create
shall display all the commands that
contains "create".
If the exact command name is found
then the
manpage for that command is displayed. If manpage does not exist
then the usage-text for the command is displayed. If
usage-text does not exist then the closest matched command names are
displayed. Regular expression is supported in finding the closest
matched command.
(See: 6328156)
Manpage
Enhancements
The manpage will have the
following enhancments:
1. There will be a separate
manpage for the common options:
user, passwordfile, host, port, terse, echo, interactive, secure and
help. The description for the common options will be removed from
all the manpages but the common options will remain in the synopsis of
the command. In the "SEE ALSO" section, the manpage of the common
options will be listed there.
2. There will be new manpages for the following concepts:
- domain
- cluster
- instance
- node-agent
- configuration
- loadbalancer
- resource
- application
- montioring
- dotted-names
- password
- logging
- security
- usage-profile
These concepts are commonly used
terms in Application Server.
Improve
asadmin command usage
text
Currently
the required/optional options are in no
particular order in the usage text. For example, create-domain
usage text:
Usage:
create-jdbc-resource [--terse=false] [--echo=false]
[--interactive=true] [--host localhost] [--port 4848|4849] [--secure |
-s] --user admin_user [--passwordfile file_name] --connectionpoolid id
[--enabled=true] [--description text] [--target target(Default server)]
jndi_name
The required options are embedded
in the optional
options. It's inconspicuous that the required options are
in the
command. In this release, the usage text will be organized
so that the
required options are the first on the list of options.
Usage:
create-jdbc-resource --user admin_user --connectionpoolid
id [--terse=false]
[--echo=false]
[--interactive=true] [--host localhost] [--port 4848|4849] [--secure |
-s] [--passwordfile file_name]
[--enabled=true] [--description text] [--target target(Default server)]
jndi_name
Asant
New Tasks
JAX-WS tasks: WsGen and
WsImport (See Bug: 6420962)
See: http://www.glassfishwiki.org/gfwiki/Wiki.jsp?page=NewAsantTasks
for the list of asant tasks.
4.2. Bug/RFE Number(s)
Aside from the bugs mentioned above, the following bugs/issues
will also be addressed:
Issue# 226 -- remove submodule admin-cli/cli-api
Issue# 434, 507 -- handle NPE in add-resources/dangerous code pattern
Issue# 694 -- space in path breaks asadmin start-domain [startserv] in
MacOS
Issue# 846 -- CLIMain incorrectly logs exceptions
Issue# 274
-- remove password attribute from all asant tasks
Issue# 1150
-- start-domain command prompts for user/password even though
.asadminpass contains the user/password info
4.3. In Scope
N/A
4.4. Out of Scope
N/A
4.5. Interfaces
http://www.opensolaris.org/os/community/arc/policies/interface-taxonomy/
describes the permitted interface taxonomy.
4.5.1 Exported Interfaces
| Interface |
Stability |
Former Stability (if changing) |
Comments |
asadmin
|
EVOLVING |
EVOLVING |
Command Line Interface Tool
|
| asant |
EVOLVING |
EVOLVING |
Contains AppServer
Ant Tasks |
4.5.2 Imported interfaces
| Interface |
Stability |
Exporting Project: Name,
Specification or other Link. |
Comments |
| AMX |
EVOLVING |
|
|
4.5.3 Other interfaces (Optional)
Not applicable.
4.6. Doc Impact
New manpages will be created for the new commands, common
options and concepts.
Exising manpages will need to be updated.
4.7. Admin/Config Impact
4.8. HA Impact
Not applicable.
4.9. I18N/L10N Impact
Not applicable.
4.10. Packaging & Delivery
N/A
4.11. Security Impact
Not applicable.
4.12. Compatibility Impact
TBD.
4.13. Dependencies
5. Reference Documents
Admin
Infrastructure One Pager
JBI
Integration One Pager
Connection
Pool Enhancements One Pager
Load
Balancer Enhancements One Pager
6. Schedule
6.1. Projected Availability
Covered elsewhere.
7. Document History
| Version |
Date
|
Author, Comment |
1.3
|
01/09/07
|
Jane Young
Updated monitor command table
Modified dotted names for connection pool attributes
Fixed margin
|
1.2
|
11/17/06
|
Jane Young
Updated section about deprecation of adminuser and
AS_ADMIN_ADMINPASSWORD. adminuser and AS_ADMIN_ADMINPASSWORD
takes precedence over user and AS_ADMNI_PASSWORD.
|
1.1
|
11/15/06
|
Jane Young
Updated section about portbase, LB commands, deprecation of adminuser
and AS_ADMIN_ADMINPASSWORD
|
1.0
|
11/14/06
|
Jane Young
Updated monitor command syntax
Updated description on --portbase option in create-domain
|
0.9
|
11/07/06
|
Jane Young
Updated monitor command syntax
added usage-profile to manpage concept
|
0.8
|
09/15/06
|
Jane Young
changed monitoring command to "monitor"
added issue 1550
|
0.7
|
9/12/06
|
Jane Young
Updated section on New Monitoring Command
|
0.6
|
09/06/06
|
Jane Young,
Updated section on Connection Pool Enhancement
|
0.5
|
09/05/06
|
Jane Young,
Modified Technical Detail Descriptrions
Removed comments
|
0.4
|
09/05/06
|
Jane Young,
Modified Technical Detail Descriptions
|
| 0.3 |
09/01/06 |
Jane Young, Kedar Mhaswade, Abhijit Kumar
Added various changes.
|
0.2
|
09/01/06
|
Jane Young,
Modified Project Summary, Technical Detail Descriptions
|
| 0.1 |
|
Kedar Mhaswade, created. |
|