| This page provides links to review drafts of new and changed documentation for the Deployment project as listed in the Deployment Documentation Plan. Mandatory reviewers for each item are listed in each section. Changes to existing documentation since the last release are marked with change bars. No changes are marked in new documentation. Please provide your feedback by adding a comment to this page. To simplify the processing of your comments, please add your comments in the format in the sample comment. Review existing comments to see known issues and avoid duplicates.
Changes to Books Application Deployment Guide Changes
| Section |
Documentation Impact |
Reviewers |
Status |
| 1 Overview of Deployment |
Moderate |
Hong Zhang, Tim Quinn |
Reviewed by Hong and Tim |
| Module and Application Versions |
NEW |
Hong Zhang, Tim Quinn |
Reviewed by Hong and Tim |
| 2 Deploying Applications |
Moderate |
Hong Zhang, Tim Quinn |
Reviewed by Hong and Tim |
Transparent JDBC Connection Pool
Reconfiguration |
NEW |
Jagadish Ramu, Shalini Muthukrishnan |
Reviewed by Jagadish |
| Application-Scoped Resources |
NEW |
Jagadish Ramu, Shalini Muthukrishnan |
Reviewed by Jagadish |
| A asadmin Deployment Subcommands |
Minor |
Hong Zhang, Tim Quinn |
Reviewed by Hong and Tim |
| B Deployment Descriptor Files |
Moderate |
Hong Zhang, Tim Quinn |
Reviewed by Hong and Tim |
WebLogic Server Deployment Descriptor
Support in GlassFish Server |
NEW |
Shing-Wai Chan, Bhakti Mehta, Rama Pulavarthi |
Reviewed by Shing-Wai and Rama |
| C Elements of Deployment Descriptors |
Moderate |
Hong Zhang, Tim Quinn |
Reviewed by Hong and Tim |
| jdbc-connection-pool element description |
Moderate |
Jagadish Ramu, Shalini Muthukrishnan |
Reviewed by Jagadish |
A PDF file of the latest Application Deployment Guide, with change bars, is here. Changes to Online Help Changes to Man Pages Mandatory reviewers in addition to the reviewers that are listed in the table are as follows:
- Elena Asarina
- Tom Mueller
| Man Page Name and Section |
Documentation Impact |
Reviewers |
| create-application-ref(1) |
Minor |
Hong Zhang, Tim Quinn |
| delete-application-ref(1) |
Minor |
Hong Zhang, Tim Quinn |
| list-application-refs(1) |
Minor |
Hong Zhang, Tim Quinn |
| create-lifecycle-module(1) |
Minor |
Hong Zhang, Tim Quinn |
| delete-lifecycle-module(1) |
Minor |
Hong Zhang, Tim Quinn |
| list-lifecycle-modules(1) |
Minor |
Hong Zhang, Tim Quinn |
| deploy(1) |
Moderate |
Hong Zhang, Tim Quinn |
| deploydir(1) |
Moderate |
Hong Zhang, Tim Quinn |
| disable(1) |
Minor |
Hong Zhang, Tim Quinn |
| enable(1) |
Minor |
Hong Zhang, Tim Quinn |
| list-applications(1) |
Moderate |
Hong Zhang, Tim Quinn |
| list-components(1) |
Moderate |
Hong Zhang, Tim Quinn |
| list-sub-components(1) |
Moderate |
Hong Zhang, Tim Quinn |
| show-component-status(1) |
Minor |
Hong Zhang, Tim Quinn |
| redeploy(1) |
Moderate |
Hong Zhang, Tim Quinn |
| undeploy(1) |
Minor |
Hong Zhang, Tim Quinn |
| Comment ID |
Location |
Comment |
| RJP-001 |
deploy(1) man page |
Sample comment. Should provide a proposed fix and correct content if applicable. |
| RJP-002 |
undeploy(1) man page |
Another sample comment. |
 Posted by rebeccaparks at Nov 03, 2010 14:00
|
| Comment ID |
Location |
Comment |
| trm-1 |
create-application-ref, delete-application-ref, create-lifecycle-module, deploy, deploydir, list-applications, list-components, redeploy, undeploy |
The --target instance_name should state that this must be a stand-alone instance, as you cannot run this on a single instance in a cluster. |
| trm-2 |
create-application-ref, delete-application-ref, list-application-refs, deploy, deploydir, disable, enable, list-applications, list-components, list-sub-components, show-component-status, redeploy, undeploy |
Update the "v3 Preview" documentation reference |
| trm-3 |
create-lifecycle-module |
Is there a default value for --loadorder?
|
| trm-4 |
create-lifecycle-module |
Under --failurefatal, typo "This options" |
| trm-5 |
create-lifecycle-module |
The last three options talk about a "resource" being enabled, having a description, etc. , but this manual page is about lifecycle modules. I don't think the word resource should be used here. |
| trm-6 |
create-lifecycle-module |
What is the format of the --classpath option? Is this really a classpath with either colon-separated (Unix) or semicolon-separated (Windows) JAR files and directories, or is this just a single JAR file? |
| trm-7 |
create-lifecycle-module |
Where is the applications root directory mentioned in the --classpath option. |
| trm-8 |
create-lifecycle-module |
The description talks about running a program at a certain "stage in the server lifecycle". Where does the reader find out about what these stages are and how to actually write one of these modules? I expect that a reference to the writing server extensions module is needed here.
|
| trm-9 |
create-lifecycle-module |
The manual page should explain what happens to a JAR file that is referenced by the classpath option? Is it copied to the server? Can it be deleted after the command is done running? (I expect yes). |
| trm-10 |
list-lifecycle-modules |
Example 1: there is a missing newline between the command and the output. |
| trm-11 |
deploy, deploydir, redeploy |
The note under --properties about the set command being unable to change properties that have an embedded dot may no longer be true. There was a bug fixed in this area in 3.1. |
| trm-12 |
disable, enable |
The --target option should state that this command does permit a single instance within a cluster to be specified. |
| trm-13 |
list-applications, list-components |
The description says that the --long option provides information about which versions are deployed, but the section on the --long option itself doesn't mention this. |
| trm-14 |
show-component-status |
This command does not allow an instance within a cluster to be specified as the target, but given that disable and enable do, there seems to be a bug here. I sent some email to Hong and Tim about this, but once that is resolved, an update to the manual page will be required. |
| trm-15 |
undeploy |
typo: "sever" in --target option |
Posted by trmueller at Nov 17, 2010 14:56
|
| Comment ID |
Location |
Comment |
| tjq-1 |
p. 42, Version Identifiers and Expressions section |
The text says a version identifier is the : plus the suffix. Then the examples of "version identifiers" show the entire name+version-ID. The latest design document uses the term "version identifier" (and version expression) to refer to the part after the colon. I think this makes sense, but do we also need a term for the combined "app-name:version-ID" and "app-name:version-spec" for elsewhere in the doc? Maybe "application identifier" and "application expression.html"?? |
| tjq-2 |
To Reload Changes to Applications or Modules Dynamically |
The text lists two steps. Only the touch command is needed. If the .reload file does not yet exist, touch will create it. If the file does exist, touch will update its revision time which triggers the redeployment. We can remove step 1. If we want to add an example for Windows, echo > domain-dir/applications/app-or-module-name/.reload will work. (The content of the file is not important. GlassFish server just looks at the file's revision time.) |
| tjq-3 |
p. 33, paragraph beginning "Deployment is the" |
I suggest using "Deployment is the process of using a deployment tool to install an applicatinor module on GlassFish server, optionally specifying location-specific information such as a list of local users that can access the application or the name of the local database." |
| tjq-4 |
p. 35, 2nd paragraph under Deployment Descriptors and Annos", sentence beginning "At run time..." |
I suggest replacing "At runtime" with "During deployment" |
| tjq-5 |
p. 37, Application Client Module bullet, last sentence |
What is "supports direct access to GlassFish Server" intended to mean? |
| tjq-6 |
p. 38, first paragraph under Application-Based Deployment |
Can we move that paragraph to p. 36 so it becomes the second paragraph under Modules and Applications? It would be nice to define both terms briefly first, plus on p. 37 the first sentence of Module-Based Deployment refers to deploying modules "outside of any application" yet we have not defined "application" yet. |
| tjq-7 |
p. 37, last sentence of 1st paragraph under Module-Based Deployment |
What do we mean by "By using package definitions in the source code of all modules...?" It sounds as if developers must add something specific to Java EE or GlassFish Server called "package definitions" to their source code. If what we mean here is the normal Java import statements (or fully-qualified class names) that any Java app would contain then let's remove this sentence. |
| tjq-8 |
p. 38, 2nd sentence under Application-Based Deployment |
Change "combine these files" to "combine these files and, optionally, deployment descriptors" |
| more to come |
|
| tjq-9 |
p. 40, the Note under Naming Standards |
By "package names" do we mean the names of Java packages in which the developer's classes reside? Or something else? (Maybe this is related to tjq-7?) The Java compiler will not accept Java package names with weird characters in them, so if that's what we mean here by "package" we don't really need to warn the developer about this. |
| tjq-10 |
p. 40, the paragraph after the Note in tjq-9 |
What exactly do we mean by a "Java package-like naming scheme?" The developer should use "/" in both the file names and the module and EJB names to make sure that files do not conflict with other files and names do not conflict with other names. If by "Java package-like" we mean "hierarchical" then let's say "hierarchical." To me, using the term "Java package-like" suggests using "." as the separator in the names, which will definitely not work. |
| tjq-11 |
p. 41, first paragraph |
"...before the archive name..." should read "...instead of the archive name..." because "before" could e interpreted as "positionally in front of." |
| tjq-12 |
same as tjq-11, 2nd and 3rd sentences |
By "a user-specified name" do we mean the name, if any, given by the --name appName option on the asadmin deploy command (or in the GUI)? This is confusing because the name given in <application-name> is also user-specified. Can we just use a bullet or numbered list giving the order in which GlassFish Server chooses the application registration name:
- --name value on the deploy command (or in the GUI) * <application-name> value from the descriptors * archive name excluding the suffix.
|
| tjq-13 |
p. 42, 1st paragraph under Module and Application Vesioning |
Insert new 2nd sentence: "At most one version of an application or module can be enabled on a server any given time." I know we say this later on also, but this is a key aspect of versioning and we should mention it here when we introduce the topic. |
| tjq-14 |
p. 43, 2nd paragraph of Choosing the Enabled Version |
Remove the reference to the deploydir command. That command is deprecated and deploy does its job now. |
| tjq-15 |
p. 44, 1st sentence under About Assembly and Deployment Events |
Change "anyone" to "any user authorized as an administrator." Now, in typically development environments people might not set up different admin users, so everyone is "authorized." But saying "anyone" without qualifying what we really mean sounds too wide open. |
| tjq-16 |
p. 44, item 1 |
Because descriptors are optional - and in fact we tend to encourage developers to use annotations rather than descriptors where possible - we should mention again that step 1 is optional and that using annotations is a good alternative. |
| tjq-17 |
p. 50, last 2-3 paragraphs |
This text duplicates what's been said earlier about how GlassFish Server chooses the application's registration name. Can we say this once, earlier, and then just refer from here to there? If we decide to replicate the text and you've changed the earlier section to use bullets or numbers, do the same here. |
| tjq-18 |
p. 59, 2nd sentence |
Replace the 2nd sentence with "The contents of the directory must be the same as the contents of a corresponding archive file, with one exception. An application archive file contains archive files for its modules, for example myUI.war and myEJB.jar. The expanded application directory contains expanded directories for the modules, for example myUI_war and myEJB_jar, instead." |
| tjq-19 |
p. 60, just before the "Before You Begin" section |
Mention that IDEs typically use directory deployment, in which case the developer does not need to deal directly with the expanded format. |
| tjq-20 |
p. 60, Example 2-20 |
The example command needs to specify the directory being deployed. either deploy hello (if the current directory contains the expanded subdirectory hello) or deploy --name hello myApp (if myApp is the expanded directory). |
| tjq-21 |
p. 71, item 5, first 3 sentences |
Change to "The client artifacts contain the ties and necessary classes for the application client. In this release of GlassFish Server the client artifacts include multiple files. You can use either deploy --retrieve or get-client-stubs but you do not need to use both. |
| tjq-22 |
p. 72, the Before You Begin sentence |
Change to "This task applies if you want to use the appclient script to run the application client on a system other than where the server runs." |
| tjq-23 |
p. 72, item 3 |
That command works fine on UNIX or Windows. No need to cite UNIX in particular. |
Posted by timq at Dec 15, 2010 20:07
|
Comment ID
|
Location
|
Comment
|
jagadish-1
|
Deployment Guide, p75
|
"However, in-progress connection requests must be retried unless the dynamic-reconfiguration-wait-timeout-in-seconds property is set." can be re-written as,
"In order to enable transaprent pool reconfiguration, the property 'dynamic-reconfiguration-wait-timeout-in-seconds' need to be set"
|
jagadish-2
|
Deployment Guide, p76 |
"You can define an application-scoped database"
can be re-written as :
"You can define an application-scoped jdbc resource |
jagadish-3
|
Deployment Guide, p76 |
"It is free from unexpected resource starvation or delay in acquiring connections."
can be re-written as :
"These resources are available only to the defining application thereby the defining application is free from unexpected resource starvation or delay in acquiring connections due to other applications" |
jagadish-4
|
Deployment Guide, p76, Section "Naming"
|
"For example, application-scoped databases have JNDI names in the following format:
java:app/jdbc/DataSourceName or java:module/jdbc/ModuleLevel/DataSourceName"
can be re-written as :
"For example, application-scoped resources have JNDI names in the following format:
java:app/jdbc/DataSourceName or java:module/jdbc/DataSourceName" |
jagadish-5
|
Deployment Guide, p77, Section "Redeployment"
|
[Property name has changed, need to update it accordingly.]
To preserve old resource definitions during redeployment, use
the preserve-app-scoped-resources property of the redeploy (or deploy --force=true)
subcommand. For example:
asadmin> redeploy --property preserve-app-scoped-resources=true MyApp.ear
asadmin> deploy --force=true --property preserve-app-scoped-resources=true MyApp.ear
can be re-written as :
To preserve old resource definitions during redeployment, use
the preserveAppScopedResources property of the redeploy (or deploy --force=true)
subcommand. For example:
asadmin> redeploy --property preserveAppScopedResources=true MyApp.ear
asadmin> deploy --force=true --property preserveAppScopedResources=true MyApp.ear
NOTE : Please update the deploy/undeploy man pages also if the property 'preserveAppScopedResources' is specified there. |
jagadish-6
|
Deployment Guide, p172, Section "Attributes" of jdbc-connection-pool
|
"Changing the following attributes requires a server restart"
can be re-written as :
"Changing the following attributes requires re-deployment (or disable and enable) of applications that refer the resources or server restart" |
jagadish-7
|
Deployment Guide, p130, Section "Attributes" of connector-connection-pool
|
"Changing the following attributes requires a server restart"
can be re-written as :
"Changing the following attributes requires re-deployment (or disable and enable) of applications that refer the resources or server restart" |
Posted by jagadish at Jan 02, 2011 20:52
|
| Comment ID |
Location |
Comment |
| shingwai-1 |
Deployment Guide, p.99 |
virtual-directory-mapping is not supported |
| shingwai-2 |
Deployment Guide, p.100 |
page-check-seconds under jsp-descriptor is not supported |
| shingwai-3 |
Deployment Guide, p.100 |
compress-html-template under jsp-descriptor
GlassFish Support: trimSpaces init parameter of JspServlet |
| shingwai-4 |
Deployment Guide, p.100 |
save-sessions-enabled under container-descriptor
GlassFish Support: keep-state glassfish-web.xml equivalent |
| shingwai-5 |
Deployment Guide, p.100 |
run-as-principal-name under servlet-descriptor
GlassFish Support: principal-name of servlet in glassfish-web.xml equivalent |
| shingwai-6 |
Deployment Guide, p.101 |
It should be glassfish-web.xml instead of glassfish-web-app.xml |
Posted by shing-wai.chan at Jan 11, 2011 15:14
|
| Comment ID |
Location |
Comment |
| tjq-24 |
p. 56, To Reload Changes |
If we are going to show two steps (changing to the directory and then using touch or echo) then the first step should not include the .reload file name. You cannot cd to a file, just the containing directory.
Also, the example for Windows needs to be echo > .reload as in my earlier comment - note the greater-than side has to be there. The revised text omitted it. |
Posted by timq at Feb 16, 2011 11:50
|
|
create-application-ref.1.pdf (application/pdf)
