From 5e133a520459c481d07f980875a574659f733eca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20Mat=C4=9Bj=C4=8Dek?= Date: Tue, 14 Dec 2021 11:09:14 +0100 Subject: [PATCH] Issue #23739 Fixed broken asciidocs in administration-guide --- .../jbake/content/asadmin-subcommands.adoc | 7 +- .../src/main/jbake/content/batch.adoc | 66 +- .../src/main/jbake/content/concurrent.adoc | 284 +++---- .../src/main/jbake/content/connectors.adoc | 415 +++++----- .../src/main/jbake/content/domains.adoc | 544 ++++++------- .../jbake/content/general-administration.adoc | 645 +++++++--------- .../src/main/jbake/content/http_https.adoc | 307 ++++---- .../src/main/jbake/content/javamail.adoc | 50 +- .../src/main/jbake/content/jdbc.adoc | 325 ++++---- .../src/main/jbake/content/jms.adoc | 717 +++++++++--------- .../src/main/jbake/content/jndi.adoc | 116 ++- .../src/main/jbake/content/jvm.adoc | 85 +-- .../main/jbake/content/lifecycle-modules.adoc | 77 +- .../src/main/jbake/content/loe.adoc | 1 + .../src/main/jbake/content/lof.adoc | 1 + .../src/main/jbake/content/logging.adoc | 396 +++++----- .../src/main/jbake/content/lot.adoc | 1 + .../src/main/jbake/content/monitoring.adoc | 289 ++++--- .../src/main/jbake/content/orb.adoc | 50 +- .../src/main/jbake/content/overview.adoc | 350 ++++----- .../main/jbake/content/part-appendixes.adoc | 6 +- .../content/part-res-and-svcs-admin.adoc | 6 +- .../jbake/content/part-runtime-admin.adoc | 6 +- .../src/main/jbake/content/preface.adoc | 1 + .../src/main/jbake/content/threadpools.adoc | 64 +- .../src/main/jbake/content/title.adoc | 24 +- .../src/main/jbake/content/transactions.adoc | 164 ++-- .../src/main/jbake/content/webapps.adoc | 290 +++---- 28 files changed, 2478 insertions(+), 2809 deletions(-) diff --git a/docs/administration-guide/src/main/jbake/content/asadmin-subcommands.adoc b/docs/administration-guide/src/main/jbake/content/asadmin-subcommands.adoc index b245a76f2910..eeff6add4e05 100644 --- a/docs/administration-guide/src/main/jbake/content/asadmin-subcommands.adoc +++ b/docs/administration-guide/src/main/jbake/content/asadmin-subcommands.adoc @@ -3,6 +3,7 @@ status=published title=Subcommands for the asadmin Utility prev=part-appendixes.html ~~~~~~ + Subcommands for the asadmin Utility =================================== @@ -43,12 +44,10 @@ provides a collection of these help pages. [NOTE] -======================================================================= - +==== The common options used with remote subcommands are described in the olink:GSRFM00263[`asadmin`(1M)] help page. - -======================================================================= +==== [[ggltk]][[GSADG00610]][[general-administration-subcommands]] diff --git a/docs/administration-guide/src/main/jbake/content/batch.adoc b/docs/administration-guide/src/main/jbake/content/batch.adoc index 90f32d59803a..8ff3d2ad489a 100644 --- a/docs/administration-guide/src/main/jbake/content/batch.adoc +++ b/docs/administration-guide/src/main/jbake/content/batch.adoc @@ -4,6 +4,7 @@ title=Administering Batch Jobs next=part-res-and-svcs-admin.html prev=lifecycle-modules.html ~~~~~~ + Administering Batch Jobs ======================== @@ -79,23 +80,20 @@ To List Batch Jobs Use the `list-batch-jobs` subcommand in remote mode to list batch jobs and job details. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List batch jobs by using the link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`list-batch-jobs`] +1. Ensure that the server is running. Remote subcommands require a running server. +2. List batch jobs by using the link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`list-batch-jobs`] subcommand. [[GSADG1081]][[sthref67]] - - Example 10-1 Listing Batch Jobs This example lists batch jobs for the default server instance, `server`. Use `list-batch-jobs -l` to list additional details. -[source,oac_no_warn] +[source] ---- asadmin> list-batch-jobs -JOBNAME INSTANCECOUNT +JOBNAME INSTANCECOUNT payroll 9 bonus 6 Command list-batch-jobs executed successfully. @@ -121,21 +119,18 @@ existing execution is restarted. Use the `list-batch-job-executions` subcommand in remote mode to list batch job executions and execution details. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List batch job executions by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List batch job executions by using the link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`list-batch-job-executions`] subcommand. [[GSADG1084]][[sthref68]] - - Example 10-2 Listing Batch Job Executions This example lists batch job executions for the default server instance, `server`, and displays specific details. Use `list-batch-job-executions -l` to list additional details. -[source,oac_no_warn] +[source] ---- asadmin> list-batch-job-executions -o=jobname,executionid,batchstatus,exitstatus JOBNAME EXECUTIONID BATCHSTATUS EXITSTATUS @@ -162,16 +157,13 @@ sequential phase of a batch job. Use the `list-batch-job-steps` subcommand in remote mode to list steps and step details for a specific batch job execution. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the execution ID of an execution by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the execution ID of an execution by using the `list-batch-job-executions` subcommand. -3. List steps for a specific batch job execution by using the +3. List steps for a specific batch job execution by using the link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`list-batch-job-steps`] subcommand. [[GSADG1087]][[sthref69]] - - Example 10-3 Listing Batch Job Steps This example lists batch job steps and specific step details for a job @@ -181,7 +173,7 @@ details. Some lines of output are omitted from this example for readability. -[source,oac_no_warn] +[source] ---- asadmin> list-batch-job-steps o=stepname,stepid,batchstatus,stepmetrics 7 STEPNAME STEPID BATCHSTATUS STEPMETRICS @@ -242,14 +234,15 @@ To List the Batch Runtime Configuration Use the `list-batch-runtime-configuration` subcommand in remote mode to display the configuration of the batch runtime. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Display the configuration of the batch runtime by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Display the configuration of the batch runtime by using the link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`list-batch-runtime-configuration`] subcommand. -3. If desired, use the `get` subcommand to view the attributes of the -data source and managed executor service resources. + -For example (output omitted): + -[source,oac_no_warn] +3. If desired, use the `get` subcommand to view the attributes of the +data source and managed executor service resources. ++ +For example (output omitted): ++ +[source] ---- asdmin> get resources.jdbc-resource.jdbc/__TimerPool.* ... @@ -258,14 +251,12 @@ asdmin> get resources.managed-executor-service.concurrent/__defaultManagedExecut ---- [[GSADG1091]][[sthref70]] - - Example 10-4 Listing the Batch Runtime Configuration This example lists the configuration of the batch runtime for the default server instance, `server`. -[source,oac_no_warn] +[source] ---- asadmin> list-batch-runtime-configuration DATASOURCELOOKUPNAME EXECUTORSERVICELOOKUPNAME @@ -291,8 +282,7 @@ configure the batch runtime. [NOTE] -======================================================================= - +==== Do not change the data source after the first batch job has been submitted to the batch runtime for execution. If the data source must be changed, stop and restart the domain and then make the change before any @@ -302,25 +292,21 @@ inaccessible. The managed executor service can be changed after a batch job has been submitted to the batch runtime without affecting execution of the job. +==== -======================================================================= - -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Configure the batch runtime by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Configure the batch runtime by using the link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`set-batch-runtime-configuration`] subcommand. [[GSADG1094]][[sthref71]] - - Example 10-5 Configuring the Batch Runtime This example configures the batch runtime for the default server instance, `server`, to use an existing managed executor service named `concurrent/Executor1`. -[source,oac_no_warn] +[source] ---- asadmin> set-batch-runtime-configuration --executorservicelookupname concurrent/Executor1 Command set-batch-runtime-configuration executed successfully. diff --git a/docs/administration-guide/src/main/jbake/content/concurrent.adoc b/docs/administration-guide/src/main/jbake/content/concurrent.adoc index 5aef2d7da2ce..36963833c4cb 100644 --- a/docs/administration-guide/src/main/jbake/content/concurrent.adoc +++ b/docs/administration-guide/src/main/jbake/content/concurrent.adoc @@ -4,6 +4,7 @@ title=Administering Concurrent Resources next=orb.html prev=http_https.html ~~~~~~ + Administering Concurrent Resources ================================== @@ -120,33 +121,28 @@ with GlassFish Server, see link:#DAFFGDCD[Default Concurrent Resources]. [NOTE] -======================================================================= - +==== Creating a context service resource is a dynamic event and typically does not require server restart. Applications can use a resource as soon as it is created. However, if an application tried to use a resource before it was created, and that resource is created later, the application or the server must be restarted. Otherwise, the application will not be able to locate the resource. +==== -======================================================================= - -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create a context service by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create a context service by using the link:../reference-manual/create-jdbc-resource.html#GSRFM00037[`create-context-service`] subcommand. -3. If necessary, notify users that the new resource has been created. +3. If necessary, notify users that the new resource has been created. [[GSADG1113]][[sthref74]] - - Example 14-1 Creating a Context Service This example creates a context service resource named `concurrent/Context1`. -[source,oac_no_warn] +[source] ---- asadmin> create-context-service concurrent/Context1 Context service concurrent/Context1 created successfully. @@ -168,20 +164,17 @@ To List Context Services Use the `list-context-services` subcommand in remote mode to list the existing context service resources. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List context service resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List context service resources by using the link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`list-context-services`] subcommand. [[GSADG1116]][[sthref75]] - - Example 14-2 Listing Context Services This example lists context service resources on the default server instance, `server`. -[source,oac_no_warn] +[source] ---- asadmin> list-context-services concurrent/__defaultContextService @@ -208,32 +201,29 @@ view and change the values of the context service attributes. [NOTE] -======================================================================= - +==== When a resource is updated, the existing resource is shut down and recreated. If an application used the resource prior to the update, the application or the server must be restarted. - -======================================================================= +==== -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the context service resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the context service resources by using the link:../reference-manual/list-jdbc-connection-pools.html#GSRFM00173[`list-context-services`] subcommand. -3. View the attributes of a specific context service by using the `get` -subcommand. + -For example: + -[source,oac_no_warn] +3. View the attributes of a specific context service by using the `get` subcommand. +For example: ++ +[source] ---- -asdmin> get resources.context-service.concurrent/Context1.* +asadmin> get resources.context-service.concurrent/Context1.* ---- -4. Set an attribute of the context service by using the `set` -subcommand. + -For example: + -[source,oac_no_warn] +4. Set an attribute of the context service by using the `set` subcommand. +For example: ++ +[source] ---- -asdmin> set resources.context-service.concurrent/Context1.deployment-order=120 +asadmin> set resources.context-service.concurrent/Context1.deployment-order=120 ---- [[DAFGGGEC]][[GSADG1119]][[to-delete-a-context-service]] @@ -248,24 +238,20 @@ and does not require server restart. Before deleting a context service resource, all associations to the resource must be removed. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the context service resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the context service resources by using the link:../reference-manual/list-jdbc-connection-pools.html#GSRFM00173[`list-context-services`] subcommand. -3. If necessary, notify users that the context service is being -deleted. -4. Delete the context service by using the +3. If necessary, notify users that the context service is being deleted. +4. Delete the context service by using the link:../reference-manual/delete-jdbc-connection-pool.html#GSRFM00088[`delete-context-service`] subcommand. [[GSADG1120]][[sthref76]] - - Example 14-3 Deleting a Context Service This example deletes the context service resource named `concurrent/Context1`. -[source,oac_no_warn] +[source] ---- asadmin> delete-context-service concurrent/Context1 Context service concurrent/Context1 deleted successfully. @@ -315,33 +301,28 @@ Resources]. [NOTE] -======================================================================= - +==== Creating a managed thread factory resource is a dynamic event and typically does not require server restart. Applications can use a resource as soon as it is created. However, if an application tried to use a resource before it was created, and that resource is created later, the application or the server must be restarted. Otherwise, the application will not be able to locate the resource. +==== -======================================================================= - -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create a managed thread factory by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create a managed thread factory by using the link:../reference-manual/create-jdbc-resource.html#GSRFM00037[`create-managed-thread-factory`] subcommand. -3. If necessary, notify users that the new resource has been created. +3. If necessary, notify users that the new resource has been created. [[GSADG1124]][[sthref77]] - - Example 14-4 Creating a Managed Thread Factory This example creates a managed thread factory resource named `concurrent/Factory1`. -[source,oac_no_warn] +[source] ---- asadmin> create-managed-thread-factory concurrent/Factory1 Managed thread factory concurrent/Factory1 created successfully. @@ -363,20 +344,17 @@ To List Managed Thread Factories Use the `list-managed-thread-factories` subcommand in remote mode to list the existing managed thread factory resources. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List managed thread factory resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List managed thread factory resources by using the link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`list-managed-thread-factories`] subcommand. [[GSADG1127]][[sthref78]] - - Example 14-5 Listing Managed Thread Factories This example lists managed thread factory resources on the default server instance, `server`. -[source,oac_no_warn] +[source] ---- asadmin> list-managed-thread-factories concurrent/__defaultManagedThreadFactory @@ -404,32 +382,29 @@ attributes. [NOTE] -======================================================================= - +==== When a resource is updated, the existing resource is shut down and recreated. If applications used the resource prior to the update, the application or the server must be restarted. - -======================================================================= +==== -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the managed thread factory resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the managed thread factory resources by using the link:../reference-manual/list-jdbc-connection-pools.html#GSRFM00173[`list-managed-thread-factories`] subcommand. -3. View the attributes of a managed thread factory by using the `get` -subcommand. + -For example: + -[source,oac_no_warn] +3. View the attributes of a managed thread factory by using the `get` subcommand. +For example: ++ +[source] ---- -asdmin> get resources.managed-thread-factory.concurrent/Factory1.* +asadmin> get resources.managed-thread-factory.concurrent/Factory1.* ---- -4. Set an attribute of the managed thread factory by using the `set` -subcommand. + -For example: + -[source,oac_no_warn] +4. Set an attribute of the managed thread factory by using the `set` subcommand. +For example: ++ +[source] ---- -asdmin> set resources.managed-thread-factory.concurrent/Factory1.deployment-order=120 +asadmin> set resources.managed-thread-factory.concurrent/Factory1.deployment-order=120 ---- [[DAFCEDEI]][[GSADG1130]][[to-delete-a-managed-thread-factory]] @@ -444,24 +419,20 @@ factory is a dynamic event and does not require server restart. Before deleting a managed thread factory resource, all associations to the resource must be removed. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the managed thread factory resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the managed thread factory resources by using the link:../reference-manual/list-jdbc-connection-pools.html#GSRFM00173[`list-managed-thread-factories`] subcommand. -3. If necessary, notify users that the managed thread factory is being -deleted. -4. Delete the managed thread factory by using the +3. If necessary, notify users that the managed thread factory is being deleted. +4. Delete the managed thread factory by using the link:../reference-manual/delete-jdbc-connection-pool.html#GSRFM00088[`delete-managed-thread-factory`] subcommand. [[GSADG1131]][[sthref79]] - - Example 14-6 Deleting a Managed Thread Factory This example deletes the managed thread factory resource named `concurrent/Factory1`. -[source,oac_no_warn] +[source] ---- asadmin> delete-managed-thread-factory concurrent/Factory1 Managed thread factory concurrent/Factory1 deleted successfully. @@ -511,33 +482,28 @@ Resources]. [NOTE] -======================================================================= - +==== Creating a managed executor service resource is a dynamic event and typically does not require server restart. Applications can use a resource as soon as it is created. However, if an application tried to use a resource before it was created, and that resource is created later, the application or the server must be restarted. Otherwise, the application will not be able to locate the resource. - -======================================================================= +==== -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create a managed executor service by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create a managed executor service by using the link:../reference-manual/create-jdbc-resource.html#GSRFM00037[`create-managed-executor-service`] subcommand. -3. If necessary, notify users that the new resource has been created. +3. If necessary, notify users that the new resource has been created. [[GSADG1135]][[sthref80]] - - Example 14-7 Creating a Managed Executor Service This example creates a managed executor service resource named `concurrent/Executor1`. -[source,oac_no_warn] +[source] ---- asadmin> create-managed-executor-service concurrent/Executor1 Managed executor service concurrent/Executor1 created successfully. @@ -560,20 +526,17 @@ To List Managed Executor Services Use the `list-managed-executor-services` subcommand in remote mode to list the existing managed executor service resources. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List managed executor service resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List managed executor service resources by using the link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`list-managed-executor-services`] subcommand. [[GSADG1138]][[sthref81]] - - Example 14-8 Listing Managed Executor Services This example lists managed executor service resources on the default server instance, `server`. -[source,oac_no_warn] +[source] ---- asadmin> list-managed-executor-services concurrent/__defaultManagedExecutorService @@ -602,32 +565,29 @@ service attributes. [NOTE] -======================================================================= - +==== When a resource is updated, the existing resource is shut down and recreated. If applications used the resource prior to the update, the application or the server must be restarted. - -======================================================================= +==== -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the managed executor service resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the managed executor service resources by using the link:../reference-manual/list-jdbc-connection-pools.html#GSRFM00173[`list-managed-executor-services`] subcommand. -3. View the attributes of a managed executor service by using the `get` -subcommand. + -For example: + -[source,oac_no_warn] +3. View the attributes of a managed executor service by using the `get` subcommand. +For example: ++ +[source] ---- -asdmin> get resources.managed-executor-service.concurrent/Executor1.* +asadmin> get resources.managed-executor-service.concurrent/Executor1.* ---- -4. Set an attribute of the managed executor service by using the `set` -subcommand. + -For example: + -[source,oac_no_warn] +4. Set an attribute of the managed executor service by using the `set` +subcommand. For example: ++ +[source] ---- -asdmin> set resources.managed-executor-service.concurrent/Executor1.deployment-order=120 +asadmin> set resources.managed-executor-service.concurrent/Executor1.deployment-order=120 ---- [[DAFDAGAD]][[GSADG1141]][[to-delete-a-managed-executor-service]] @@ -642,24 +602,20 @@ service is a dynamic event and does not require server restart. Before deleting a managed executor service resource, all associations to the resource must be removed. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the managed executor service resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the managed executor service resources by using the link:../reference-manual/list-jdbc-connection-pools.html#GSRFM00173[`list-managed-executor-services`] subcommand. -3. If necessary, notify users that the managed executor service is -being deleted. -4. Delete the managed executor service by using the +3. If necessary, notify users that the managed executor service is being deleted. +4. Delete the managed executor service by using the link:../reference-manual/delete-jdbc-connection-pool.html#GSRFM00088[`delete-managed-executor-service`] subcommand. [[GSADG1142]][[sthref82]] - - Example 14-9 Deleting a Managed Executor Service This example deletes the managed executor service resource named `concurrent/Executor1`. -[source,oac_no_warn] +[source] ---- asadmin> delete-managed-executor-service concurrent/Executor1 Managed executor service concurrent/Executor1 deleted successfully. @@ -712,33 +668,27 @@ link:#DAFFGDCD[Default Concurrent Resources]. [NOTE] ======================================================================= - Creating a managed scheduled executor service resource is a dynamic event and typically does not require server restart. Applications can use a resource as soon as it is created. However, if an application tried to use a resource before it was created, and that resource is created later, the application or the server must be restarted. Otherwise, the application will not be able to locate the resource. - ======================================================================= -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create a managed scheduled executor service by using the -link:../reference-manual/create-jdbc-resource.html#GSRFM00037[`create-managed-scheduled-executor-service`] -subcommand. -3. If necessary, notify users that the new resource has been created. +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create a managed scheduled executor service by using the +link:../reference-manual/create-jdbc-resource.html#GSRFM00037[`create-managed-scheduled-executor-service`] subcommand. +3. If necessary, notify users that the new resource has been created. [[GSADG1146]][[sthref83]] - - Example 14-10 Creating a Managed Scheduled Executor Service This example creates a managed scheduled executor service resource named `concurrent/ScheduledExecutor1`. -[source,oac_no_warn] +[source] ---- asadmin> create-managed-scheduled-executor-service concurrent/ScheduledExecutor1 Managed scheduled executor service concurrent/ScheduledExecutor1 created successfully. @@ -761,20 +711,17 @@ To List Managed Scheduled Executor Services Use the `list-managed-scheduled-executor-services` subcommand in remote mode to list the existing managed scheduled executor service resources. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List managed scheduled executor service resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List managed scheduled executor service resources by using the link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`list-managed-scheduled-executor-services`] subcommand. [[GSADG1149]][[sthref84]] - - Example 14-11 Listing Managed Scheduled Executor Services This example lists managed scheduled executor service resources on the default server instance, `server`. -[source,oac_no_warn] +[source] ---- asadmin> list-managed-scheduled-executor-services concurrent/__defaultManagedScheduledExecutorService @@ -801,34 +748,30 @@ executor service resource except its JNDI name. Use the `get` and `set` subcommands to view and change the values of the managed scheduled executor service attributes. - [NOTE] ======================================================================= - When a resource is updated, the existing resource is shut down and recreated. If applications used the resource prior to the update, the application or the server must be restarted. - ======================================================================= -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the managed scheduled executor service resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the managed scheduled executor service resources by using the link:../reference-manual/list-jdbc-connection-pools.html#GSRFM00173[`list-managed-scheduled-executor-services`] subcommand. -3. View the attributes of a managed scheduled executor service by using -the `get` subcommand. + -For example: + -[source,oac_no_warn] +3. View the attributes of a managed scheduled executor service by using the `get` subcommand. +For example: ++ +[source] ---- -asdmin> get resources.managed-scheduled-executor-service.concurrent/ScheduledExecutor1.* +asadmin> get resources.managed-scheduled-executor-service.concurrent/ScheduledExecutor1.* ---- -4. Set an attribute of the managed scheduled executor service by using -the `set` subcommand. + -For example: + -[source,oac_no_warn] +4. Set an attribute of the managed scheduled executor service by using +the `set` subcommand. For example: ++ +[source] ---- -asdmin> set resources.managed-scheduled-executor-service.concurrent/ScheduledExecutor1.deployment-order=120 +asadmin> set resources.managed-scheduled-executor-service.concurrent/ScheduledExecutor1.deployment-order=120 ---- [[DAFEBEGC]][[GSADG1152]][[to-delete-a-managed-scheduled-executor-service]] @@ -844,25 +787,20 @@ require server restart. Before deleting a managed scheduled executor service resource, all associations to the resource must be removed. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the managed scheduled executor service resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the managed scheduled executor service resources by using the link:../reference-manual/list-jdbc-connection-pools.html#GSRFM00173[`list-managed-scheduled-executor-service`] subcommand. -3. If necessary, notify users that the managed scheduled executor -service is being deleted. -4. Delete the managed scheduled executor service by using the -link:../reference-manual/delete-jdbc-connection-pool.html#GSRFM00088[`delete-managed-scheduled-executor-service`] -subcommand. +3. If necessary, notify users that the managed scheduled executor service is being deleted. +4. Delete the managed scheduled executor service by using the +link:../reference-manual/delete-jdbc-connection-pool.html#GSRFM00088[`delete-managed-scheduled-executor-service`] subcommand. [[GSADG1153]][[sthref85]] - - Example 14-12 Deleting a Managed Scheduled Executor Service This example deletes the managed scheduled executor service resource named `concurrent/ScheduledExecutor1`. -[source,oac_no_warn] +[source] ---- asadmin> delete-managed-scheduled-executor-service concurrent/ScheduledExecutor1 Managed scheduled executor service concurrent/ScheduledExecutor1 deleted successfully. diff --git a/docs/administration-guide/src/main/jbake/content/connectors.adoc b/docs/administration-guide/src/main/jbake/content/connectors.adoc index 64e395c53a37..1536bc57ae45 100644 --- a/docs/administration-guide/src/main/jbake/content/connectors.adoc +++ b/docs/administration-guide/src/main/jbake/content/connectors.adoc @@ -4,6 +4,7 @@ title=Administering EIS Connectivity next=http_https.html prev=jdbc.html ~~~~~~ + Administering EIS Connectivity ============================== @@ -21,14 +22,12 @@ utility. [NOTE] -======================================================================= - +==== If you installed the Web Profile, connector modules that use only outbound communication features and work-management that does not involve inbound communication features are supported. Other connector features are supported only in the Full Platform Profile. - -======================================================================= +==== The following topics are addressed here: @@ -103,21 +102,24 @@ Objects]. At runtime, the following sequence occurs when an application connects to an EIS: -1. The application gets the connector resource (data source) associated -with the EIS by making a call through the JNDI API. + +1. The application gets the connector resource (data source) associated +with the EIS by making a call through the JNDI API. ++ Using the JNDI name of the connector resource, the naming and directory service locates the resource. Each EIS resource specifies a connector connection pool. -2. Using the connector resource, the application gets an EIS -connection. + +2. Using the connector resource, the application gets an EIS +connection. ++ GlassFish Server retrieves a physical connection from the connection pool that corresponds to the EIS resource. The pool defines connection attributes such as the EIS name, user name, and password. -3. After the EIS connection is established, the application can read, -modify, and add data to the EIS. + +3. After the EIS connection is established, the application can read, +modify, and add data to the EIS. ++ The application accesses the EIS information by making calls to the JMS API. -4. When the application is finished accessing the EIS, the application +4. When the application is finished accessing the EIS, the application closes the connection and returns the connection to the connection pool. [[ablls]][[GSADG00581]][[administering-connector-connection-pools]] @@ -162,34 +164,34 @@ Before You Begin Before creating the connector connection pool, the connector must be installed. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create the connector connection pool by using the -link:../reference-manual/create-connector-connection-pool.html#GSRFM00018[`create-connector-connection-pool`] subcommand. + +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create the connector connection pool by using the +link:../reference-manual/create-connector-connection-pool.html#GSRFM00018[`create-connector-connection-pool`] subcommand. ++ Information about properties for the subcommand is included in this help page. -3. If needed, restart the server. + +3. If needed, restart the server. ++ Some properties require server restart. See link:overview.html#ghciy[Configuration Changes That Require Restart]. If your server needs to be restarted, see link:domains.html#ginqj[To Restart a Domain]. -4. You can verify that a connection pool is usable by using the -`ping-connection-pool` subcommand. + +4. You can verify that a connection pool is usable by using the +`ping-connection-pool` subcommand. ++ For instructions, see link:jdbc.html#ggnwn[To Contact (Ping) a Connection Pool]. [[GSADG00223]][[giocc]] - - Example 12-1 Creating a Connector Connection Pool This example creates the new `jms/qConnPool` pool for the `jakarta.jms.QueueConnectionFactory` connector module. -[source,oac_no_warn] +[source] ---- -asadmin> create-connector-connection-pool --steadypoolsize 20 --maxpoolsize 100 ---poolresize 2 --maxwait 60000 --raname jmsra --connectiondefinition +asadmin> create-connector-connection-pool --steadypoolsize 20 --maxpoolsize 100 +--poolresize 2 --maxwait 60000 --raname jmsra --connectiondefinition jakarta.jms.QueueConnectionFactory jms/qConnPool Command create-connector-connection-pool executed successfully @@ -211,19 +213,16 @@ To List Connector Connection Pools Use the `list-connector-connection-pools` subcommand in remote mode to list the pools that have been created. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the connector connection pools by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the connector connection pools by using the link:../reference-manual/list-connector-connection-pools.html#GSRFM00157[`list-connector-connection-pools`] subcommand. [[GSADG00224]][[giody]] - - Example 12-2 Listing Connector Connection Pools This example lists the existing connector connection pools. -[source,oac_no_warn] +[source] ---- asadmin> list-connector-connection-pools jms/qConnPool @@ -249,9 +248,8 @@ link:jdbc.html#ggnwn[To Contact (Ping) a Connection Pool] or link:jdbc.html#gjiqp[To Reset (Flush) a Connection Pool] for instructions. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Connect to or reset a connector connection pool by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Connect to or reset a connector connection pool by using the link:../reference-manual/flush-connection-pool.html#GSRFM00135[`flush-connection-pool`] subcommand or the link:../reference-manual/ping-connection-pool.html#GSRFM00214[`ping-connection-pool`] subcommand. @@ -263,28 +261,27 @@ To Update a Connector Connection Pool Use the `get` and `set` subcommands to view and change the values of the connector connection pool properties. -1. List the connector connection pools by using the +1. List the connector connection pools by using the link:../reference-manual/list-connector-connection-pools.html#GSRFM00157[`list-connector-connection-pools`] subcommand. -2. View the properties of the connector connection pool by using the -link:../reference-manual/get.html#GSRFM00139[`get`] subcommand. + -For example: + -[source,oac_no_warn] +2. View the properties of the connector connection pool by using the +link:../reference-manual/get.html#GSRFM00139[`get`] subcommand. For example: ++ +[source] ---- asadmin> get domain.resources.connector-connection-pool.conectionpoolname.* ---- -3. Set the property of the connector connection pool by using the -link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. + -For example: + -[source,oac_no_warn] +3. Set the property of the connector connection pool by using the +link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. +For example: ++ +[source] ---- asadmin> set domain.resources.connector-connection-pool .conectionpoolname.validate-atmost-once-period-in-seconds=3 ---- -4. If needed, restart the server. + -Some properties require server restart. See -link:overview.html#ghciy[Configuration Changes That Require Restart]. If -your server needs to be restarted, see link:domains.html#ginqj[To Restart -a Domain]. +4. If needed, restart the server. Some properties require server restart. +See link:overview.html#ghciy[Configuration Changes That Require Restart]. +If your server needs to be restarted, see link:domains.html#ginqj[To Restart a Domain]. [[giocp]][[GSADG00435]][[to-delete-a-connector-connection-pool]] @@ -294,23 +291,19 @@ To Delete a Connector Connection Pool Use the `delete-connector-connection-pool` subcommand in remote mode to remove a connector connection pool. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the connector connection pools by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the connector connection pools by using the link:../reference-manual/list-connector-connection-pools.html#GSRFM00157[`list-connector-connection-pools`] subcommand. -3. If necessary, notify users that the connector connection pool is -being deleted. -4. Delete the connector connection pool by using the +3. If necessary, notify users that the connector connection pool is being deleted. +4. Delete the connector connection pool by using the link:../reference-manual/delete-connector-connection-pool.html#GSRFM00070[`delete-connector-connection-pool`] subcommand. [[GSADG00225]][[giohd]] - - Example 12-3 Deleting a Connector Connection Pool This example deletes the connection pool named `jms/qConnPool`. -[source,oac_no_warn] +[source] ---- asadmin> delete-connector-connection-pool --cascade=false jms/qConnPool Command delete-connector-connection-pool executed successfully @@ -361,29 +354,28 @@ Before creating a connector resource, you must first create a connector connection pool. For instructions, see link:#gioce[To Create a Connector Connection Pool]. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create the connector resource by using the -link:../reference-manual/create-connector-resource.html#GSRFM00019[`create-connector-resource`] subcommand. + +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create the connector resource by using the +link:../reference-manual/create-connector-resource.html#GSRFM00019[`create-connector-resource`] subcommand. ++ Information about properties for the subcommand is included in this help page. -3. If needed, restart the server. + +3. If needed, restart the server. ++ Some properties require server restart. See link:overview.html#ghciy[Configuration Changes That Require Restart]. If your server needs to be restarted, see link:domains.html#ginqj[To Restart a Domain]. [[GSADG00226]][[giogn]] - - Example 12-4 Creating a Connector Resource This example creates a new resource named `jms/qConnFactory` for the `jms/qConnPool` connection pool. -[source,oac_no_warn] +[source] ---- -asadmin> create-connector-resource --poolname jms/qConnPool +asadmin> create-connector-resource --poolname jms/qConnPool --description "creating sample connector resource" jms/qConnFactory Command create-connector-resource executed successfully ---- @@ -403,19 +395,16 @@ To List Connector Resources Use the `list-connector-resources` subcommand in remote mode to list the connector resources that have been created. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the connector connection pools by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the connector connection pools by using the link:../reference-manual/list-connector-resources.html#GSRFM00158[`list-connector-resources`] subcommand. [[GSADG00227]][[gioia]] - - Example 12-5 Listing Connector Resources This example lists the existing connector resources. -[source,oac_no_warn] +[source] ---- asadmin> list-connector-resources jms/qConnFactory @@ -437,27 +426,27 @@ To Update a Connector Resource Use the `get` and `set` subcommands to view and change the values of the connector resource properties. -1. List the connector connection pools by using the +1. List the connector connection pools by using the link:../reference-manual/list-connector-resources.html#GSRFM00158[`list-connector-resources`] subcommand. -2. View the properties of the connector resource by using the -link:../reference-manual/get.html#GSRFM00139[`get`] subcommand. + -For example + -[source,oac_no_warn] +2. View the properties of the connector resource by using the +link:../reference-manual/get.html#GSRFM00139[`get`] subcommand. +For example ++ +[source] ---- asadmin> get domain.resources.connector-resource.jms/qConnFactory ---- -3. Set the property of the connector resource by using the -link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. + -For example: + -[source,oac_no_warn] +3. Set the property of the connector resource by using the +link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. +For example: ++ +[source] ---- asadmin> set domain.resources.connector-resource.jms/qConnFactory.enabled=true ---- -4. If needed, restart the server. + -Some properties require server restart. See -link:overview.html#ghciy[Configuration Changes That Require Restart]. If -your server needs to be restarted, see link:domains.html#ginqj[To Restart -a Domain]. +4. If needed, restart the server. Some properties require server restart. +See link:overview.html#ghciy[Configuration Changes That Require Restart]. +If your server needs to be restarted, see link:domains.html#ginqj[To Restart a Domain]. [[giofs]][[GSADG00439]][[to-delete-a-connector-resource]] @@ -471,28 +460,23 @@ a connector resource by specifying the JNDI name. Before You Begin -Before deleting a resource, all associations with the resource must be -removed. +Before deleting a resource, all associations with the resource must be removed. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the connector connection pools by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the connector connection pools by using the link:../reference-manual/list-connector-resources.html#GSRFM00158[`list-connector-resources`] subcommand. -3. If necessary, notify users that the connector resource is being -deleted. -4. Delete the connector resource by using the +3. If necessary, notify users that the connector resource is being deleted. +4. Delete the connector resource by using the link:../reference-manual/delete-connector-resource.html#GSRFM00071[`delete-connector-resource`] subcommand. [[GSADG00228]][[giokh]] - - Example 12-6 Deleting a Connector Resource This example deletes the `jms/qConnFactory` connector resource. -[source,oac_no_warn] +[source] ---- -asadmin> delete-connector-resource jms/qConnFactory +asadmin> delete-connector-resource jms/qConnFactory Command delete-connector-resources executed successfully ---- @@ -529,23 +513,21 @@ of deployment. The resource adapter configuration can also be created after the resource adapter is deployed. In this situation, the resource adapter is restarted with the new configuration. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create configuration information by using the -link:../reference-manual/create-resource-adapter-config.html#GSRFM00054[`create-resource-adapter-config`] subcommand. + +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create configuration information by using the +link:../reference-manual/create-resource-adapter-config.html#GSRFM00054[`create-resource-adapter-config`] subcommand. ++ Information about properties for the subcommand is included in this help page. [[GSADG00229]][[gionp]] - - Example 12-7 Creating a Resource Adapter Configuration This example creates the configuration for resource adapter `ra1`. -[source,oac_no_warn] +[source] ---- -asadmin> create-resource-adapter-config --property foo=bar +asadmin> create-resource-adapter-config --property foo=bar --threadpoolid mycustomerthreadpool ra1 Command create-resource-adapter-config executed successfully ---- @@ -568,19 +550,16 @@ list the configuration information contained in the domain configuration file (`domain.xml`) for the specified resource adapter (connector module). -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the configurations for a resource adapter by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the configurations for a resource adapter by using the link:../reference-manual/list-resource-adapter-configs.html#GSRFM00196[`list-resource-adapter-configs`] subcommand. [[GSADG00230]][[gioof]] - - Example 12-8 Listing Configurations for a Resource Adapter This example lists all the resource adapter configurations. -[source,oac_no_warn] +[source] ---- asadmin> list-resource-adapter-configs ra1 @@ -603,19 +582,21 @@ To Update a Resource Adapter Configuration Use the `get` and `set` subcommands to view and change the values of the resource adapter configuration properties. -1. List the configurations for a resource adapter by using the +1. List the configurations for a resource adapter by using the link:../reference-manual/list-resource-adapter-configs.html#GSRFM00196[`list-resource-adapter-configs`] subcommand. -2. View the properties of the connector resource by using the -link:../reference-manual/get.html#GSRFM00139[`get`] subcommand. + -For example: + -[source,oac_no_warn] +2. View the properties of the connector resource by using the +link:../reference-manual/get.html#GSRFM00139[`get`] subcommand. +For example: ++ +[source] ---- asadmin>get domain.resources.resource-adapter-config.ra1.* ---- -3. Set the property of the connector resource by using the -link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. + -For example: + -[source,oac_no_warn] +3. Set the property of the connector resource by using the +link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. +For example: ++ +[source] ---- asadmin> set domain.resources.resource-adapter-config.ra1.raSpecificProperty=value ---- @@ -630,21 +611,18 @@ delete the configuration information contained in the domain configuration file (`domain.xml`) for a specified resource adapter (connector module). -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the configurations for a resource adapter by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the configurations for a resource adapter by using the link:../reference-manual/list-resource-adapter-configs.html#GSRFM00196[`list-resource-adapter-configs`] subcommand. -3. Delete the configuration for a resource adapter by using the +3. Delete the configuration for a resource adapter by using the link:../reference-manual/delete-resource-adapter-config.html#GSRFM00106[`delete-resource-adapter-config`] subcommand. [[GSADG00231]][[giorj]] - - Example 12-9 Deleting a Resource Adapter Configuration This example deletes the configuration for resource adapter `ra1`. -[source,oac_no_warn] +[source] ---- asadmin> delete-resource-adapter-config ra1 Command delete-resource-adapter-config executed successfully @@ -703,29 +681,28 @@ For this subcommand to succeed, you must have first created a connector connection pool. For instructions, see link:#gioce[To Create a Connector Connection Pool]. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create a connector security map by using the -link:../reference-manual/create-connector-security-map.html#GSRFM00020[`create-connector-security-map`] subcommand. + +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create a connector security map by using the +link:../reference-manual/create-connector-security-map.html#GSRFM00020[`create-connector-security-map`] subcommand. ++ Information about the options for the subcommand is included in this help page. -3. If needed, restart the server. + +3. If needed, restart the server. ++ Some properties require server restart. See link:overview.html#ghciy[Configuration Changes That Require Restart]. If your server needs to be restarted, see link:domains.html#ginqj[To Restart a Domain]. [[GSADG00232]][[giuxc]] - - Example 12-10 Creating a Connector Security Map This example creates a connector security map `securityMap1` for `connection-pool1`. -[source,oac_no_warn] +[source] ---- -asadmin> create-connector-security-map --poolname connector-pool1 +asadmin> create-connector-security-map --poolname connector-pool1 --principals principal1, principal2 --mappedusername backend-username securityMap1 Command create-connector-security-map executed successfully ---- @@ -741,38 +718,33 @@ connection pool. You can get a simple listing of the connector security maps for a connector connection pool, or you can get a more comprehensive listing that shows the principals of the map. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List existing connector connection pools by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List existing connector connection pools by using the link:../reference-manual/list-connector-connection-pools.html#GSRFM00157[`list-connector-connection-pools`] subcommand. -3. List the security maps for a specific connector connection pool by +3. List the security maps for a specific connector connection pool by using the link:../reference-manual/list-connector-security-maps.html#GSRFM00159[`list-connector-security-maps`] subcommand. [[GSADG00233]][[giuwj]] - - Example 12-11 Listing All Connector Security Maps for a Connector Connection Pool This example lists the connector security maps associated with `connector-Pool1`. -[source,oac_no_warn] +[source] ---- asadmin> list-connector-security-maps connector-Pool1 -securityMap1 +securityMap1 Command list-connector-security-maps executed successfully. ---- [[GSADG00234]][[giuyc]] - - Example 12-12 Listing Principals for a Specific Security Map for a Connector Connection Pool This example lists the principals associated with `securityMap1`. -[source,oac_no_warn] +[source] ---- asadmin> list-connector-security-maps --securitymap securityMap1 connector-Pool1 principal1 @@ -781,15 +753,13 @@ Command list-connector-security-maps executed successfully. ---- [[GSADG00235]][[giuuf]] - - Example 12-13 Listing Principals of All Connector Security Maps for a Connector Connection Pool This example lists the connector security maps associated with `connector-Pool1`. -[source,oac_no_warn] +[source] ---- asadmin> list-connector-security-maps --verbose connector-Pool1 securityMap1 @@ -807,28 +777,26 @@ Use the `update-connector-security-map` subcommand in remote mode to create or modify a security map for the specified connector connection pool. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List existing connector security maps by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List existing connector security maps by using the link:../reference-manual/list-connector-security-maps.html#GSRFM00159[`list-connector-security-maps`] subcommand. -3. Modify a security map for a specific connector connection pool by +3. Modify a security map for a specific connector connection pool by using the link:../reference-manual/update-connector-security-map.html#GSRFM00252[`update-connector-security-map`] subcommand. -4. If needed, restart the server. + +4. If needed, restart the server. ++ Some properties require server restart. See link:overview.html#ghciy[Configuration Changes That Require Restart]. If your server needs to be restarted, see link:domains.html#ginqj[To Restart a Domain]. [[GSADG00236]][[giuwi]] - - Example 12-14 Updating a Connector Security Map This example adds principals to `securityMap1`. -[source,oac_no_warn] +[source] ---- -asadmin> update-connector-security-map --poolname connector-pool1 +asadmin> update-connector-security-map --poolname connector-pool1 --addprincipals principal1, principal2 securityMap1 Command update-connector-security-map executed successfully. ---- @@ -841,23 +809,21 @@ To Delete a Connector Security Map Use the `delete-connector-security-map` subcommand in remote mode to delete a security map for the specified connector connection pool. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List existing connector connection pools by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List existing connector connection pools by using the link:../reference-manual/list-connector-connection-pools.html#GSRFM00157[`list-connector-connection-pools`] subcommand. -3. Delete a security map for a specific connector connection pool by -using the link:../reference-manual/delete-connector-security-map.html#GSRFM00072[`delete-connector-security-map`] subcommand. + +3. Delete a security map for a specific connector connection pool by +using the link:../reference-manual/delete-connector-security-map.html#GSRFM00072[`delete-connector-security-map`] subcommand. ++ Information about options for this subcommand is included in this help page. [[GSADG00237]][[giuvr]] - - Example 12-15 Deleting a Connector Security Map This example deletes `securityMap1` from `connector-pool1`. -[source,oac_no_warn] +[source] ---- asadmin> delete-connector-security-map --poolname connector-pool1 securityMap1 @@ -907,30 +873,29 @@ Before creating a connector work security map, you must first create a connector connection pool. For instructions, see link:#gioce[To Create a Connector Connection Pool]. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create the connector work security map by using the -link:../reference-manual/create-connector-work-security-m.html#GSRFM00021[`create-connector-work-security-map`] subcommand. + +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create the connector work security map by using the +link:../reference-manual/create-connector-work-security-m.html#GSRFM00021[`create-connector-work-security-map`] subcommand. ++ Information about properties for the subcommand is included in this help page. -3. If needed, restart the server. + +3. If needed, restart the server. ++ Some properties require server restart. See link:overview.html#ghciy[Configuration Changes That Require Restart]. If your server needs to be restarted, see link:domains.html#ginqj[To Restart a Domain]. [[GSADG00238]][[giokw]] - - Example 12-16 Creating Connector Work Security Maps The following examples create `workSecurityMap1` and `workSecurityMap2` for `my-resource-adapter-name`. -[source,oac_no_warn] +[source] ---- -asadmin> create-connector-work-security-map --raname my-resource-adapter-name ---principalsmap eis-principal-1=server-principal-1,eis-principal-2=server-principal-2, +asadmin> create-connector-work-security-map --raname my-resource-adapter-name +--principalsmap eis-principal-1=server-principal-1,eis-principal-2=server-principal-2, eis-principal-3=server-principal-1 workSecurityMap1 asadmin> create-connector-work-security-map --raname my-resource-adapter-name @@ -955,19 +920,16 @@ To List Connector Work Security Maps Use the `list-connector-work-security-maps` subcommand in remote mode to list the work security maps that belong to a specific connector module. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the connector work security maps by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the connector work security maps by using the link:../reference-manual/list-connector-work-security-map.html#GSRFM00160[`list-connector-work-security-maps`] subcommand. [[GSADG00239]][[gionj]] - - Example 12-17 Listing the Connector Work Security Maps This example lists the generic work security maps. -[source,oac_no_warn] +[source] ---- asadmin> list-connector-work-security-maps generic-ra generic-ra-groups-map: EIS group=eis-group, mapped group=glassfish-group @@ -993,23 +955,20 @@ Use the `update-connector-work-security-map` subcommand in remote to modify a work security map that belongs to a specific resource adapter (connector module). -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the connector work security maps by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the connector work security maps by using the link:../reference-manual/list-connector-work-security-map.html#GSRFM00160[`list-connector-work-security-maps`] subcommand. -3. If necessary, notify users that the connector work security map is +3. If necessary, notify users that the connector work security map is being modified. -4. Update a connector work security map by using the +4. Update a connector work security map by using the link:../reference-manual/update-connector-work-security-m.html#GSRFM00253[`update-connector-work-security-map`] subcommand. [[GSADG00240]][[gioll]] - - Example 12-18 Updating a Connector Work Security Map This example removes a principal from a work security map. -[source,oac_no_warn] +[source] ---- asadmin> update-connector-work-security-map --raname generic-ra --removeprincipals eis-foo generic-ra-principals-map @@ -1033,22 +992,19 @@ Use the `delete-connector-work-security-map` subcommand in remote mode to delete a work security map that belongs to a specific connector module (resource adapter). -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the connector work security maps by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the connector work security maps by using the link:../reference-manual/list-connector-work-security-map.html#GSRFM00160[`list-connector-work-security-maps`] subcommand. -3. Delete a connector work security map by using the +3. Delete a connector work security map by using the link:../reference-manual/delete-connector-work-security-m.html#GSRFM00073[`delete-connector-work-security-map`] subcommand. [[GSADG00241]][[giolk]] - - Example 12-19 Deleting a Connector Work Security Map This example deletes the `worksecuritymap1` map from the `my_ra` connector module. -[source,oac_no_warn] +[source] ---- asadmin> delete-connector-work-security-map --raname my_ra worksecuritymap1 Command delete-connector-work-security-map executed successfully. @@ -1096,26 +1052,26 @@ Before You Begin The resource adapter must be deployed before running this subcommand (`jmsrar.rar`). -1. Create an administered object by using the -link:../reference-manual/create-admin-object.html#GSRFM00012[`create-admin-object`] subcommand. + +1. Create an administered object by using the +link:../reference-manual/create-admin-object.html#GSRFM00012[`create-admin-object`] subcommand. ++ Information about properties for the subcommand is included in this help page. -2. If needed, restart the server. + +2. If needed, restart the server. ++ Some properties require server restart. See link:overview.html#ghciy[Configuration Changes That Require Restart]. If your server needs to be restarted, see link:domains.html#ginqj[To Restart a Domain]. [[GSADG00242]][[giokx]] - - Example 12-20 Creating an Administered Object For this example, the `jakarta.jms.Queue` resource type is obtained from the `ra.xml` file. The JNDI name of the new administered object is `jms/samplequeue`. -[source,oac_no_warn] +[source] ---- asadmin> create-admin-object --restype jakarta.jms.Queue --raname jmsra --description "sample administered object" --property Name=sample_jmsqueue jms/samplequeue @@ -1137,19 +1093,16 @@ To List Administered Objects Use the `list-admin-object` subcommand in remote mode to list the existing administered objects. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the administered objects by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the administered objects by using the link:../reference-manual/list-admin-objects.html#GSRFM00146[`list-admin-objects`] subcommand. [[GSADG00243]][[giokg]] - - Example 12-21 Listing Administered Objects This example lists the existing administered objects. -[source,oac_no_warn] +[source] ---- asadmin> list-admin-objects jms/samplequeue @@ -1171,52 +1124,48 @@ To Update an Administered Object Use the `get` and `set` subcommands to view and change the values of the administered objects properties. -1. List the administered objects by using the +1. List the administered objects by using the link:../reference-manual/list-admin-objects.html#GSRFM00146[`list-admin-objects`] subcommand. -2. View the properties of the administered object by using the -link:../reference-manual/get.html#GSRFM00139[`get`] subcommand. + -For example: + -[source,oac_no_warn] +2. View the properties of the administered object by using the +link:../reference-manual/get.html#GSRFM00139[`get`] subcommand. +For example: ++ +[source] ---- -asadmin> get domain.resources.admin-object-resource.jms/samplequeue.* +asadmin> get domain.resources.admin-object-resource.jms/samplequeue.* ---- -3. Set the property of the administered object by using the -link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. + -For example: + -[source,oac_no_warn] +3. Set the property of the administered object by using the +link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. +For example: ++ +[source] ---- asadmin> set domain.resources.admin-object-resource.jms/samplequeue.enabled=false ---- -4. If needed, restart the server. + -Some properties require server restart. See -link:overview.html#ghciy[Configuration Changes That Require Restart]. If -your server needs to be restarted, see link:domains.html#ginqj[To Restart -a Domain]. +4. If needed, restart the server. Some properties require server restart. +See link:overview.html#ghciy[Configuration Changes That Require Restart]. +If your server needs to be restarted, see link:domains.html#ginqj[To Restart a Domain]. [[gioma]][[GSADG00455]][[to-delete-an-administered-object]] To Delete an Administered Object ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Use the `delete-admin-object` subcommand to delete an administered -objects. +Use the `delete-admin-object` subcommand to delete an administered objects. -1. List the administered objects by using the +1. List the administered objects by using the link:../reference-manual/list-admin-objects.html#GSRFM00146[`list-admin-objects`] subcommand. -2. If necessary, notify users that the administered object is being -deleted. -3. Delete an administered object by using the +2. If necessary, notify users that the administered object is being deleted. +3. Delete an administered object by using the link:../reference-manual/delete-admin-object.html#GSRFM00063[`delete-admin-object`] subcommand. [[GSADG00244]][[giolc]] - - Example 12-22 Deleting an Administered Object This example deletes the administered object with the JNDI name `jms/samplequeue`. -[source,oac_no_warn] +[source] ---- asadmin> delete-admin-object jms/samplequeue Command delete-admin-object executed successfully diff --git a/docs/administration-guide/src/main/jbake/content/domains.adoc b/docs/administration-guide/src/main/jbake/content/domains.adoc index a6fa9a82ac52..6f0957014fac 100644 --- a/docs/administration-guide/src/main/jbake/content/domains.adoc +++ b/docs/administration-guide/src/main/jbake/content/domains.adoc @@ -4,6 +4,7 @@ title=Administering Domains next=jvm.html prev=general-administration.html ~~~~~~ + Administering Domains ===================== @@ -23,8 +24,7 @@ The following topics are addressed here: * link:#ggoek[About Administering Domains] * link:#gitvz[Creating, Logging In To, and Deleting a Domain] * link:#gitwj[Starting and Stopping a Domain] -* link:#gglqp[Configuring a DAS or a GlassFish Server Instance for -Automatic Restart] +* link:#gglqp[Configuring a DAS or a GlassFish Server Instance for Automatic Restart] * link:#gityo[Backing Up and Restoring a Domain] * link:#gglri[Re-Creating the Domain Administration Server (DAS)] * link:#gitvn[Additional Domain Tasks] @@ -173,26 +173,22 @@ You are required to specify an administrative user when you create a domain, or you can accept the default login identity which is username `admin` with no password. -1. Select a name for the domain that you are creating. + +1. Select a name for the domain that you are creating. You can verify that a name is not already in use by using the link:../reference-manual/list-domains.html#GSRFM00163[`list-domains`] subcommand -2. Create a domain by using the link:../reference-manual/create-domain.html#GSRFM00023[`create-domain`] -subcommand. + -Information about the options for this subcommand is included in this -help page. -3. Type an admin user name and password for the domain. + +2. Create a domain by using the link:../reference-manual/create-domain.html#GSRFM00023[`create-domain`] subcommand. +Information about the options for this subcommand is included in this help page. +3. Type an admin user name and password for the domain. To avoid setting up an admin login, you can accept the default `admin`, with no password. Pressing Return also selects the default. [[GSADG00126]][[ggoeu]] - - Example 3-1 Creating a Domain This example creates a domain named `domain1` . When you type the command, you might be prompted for login information. -[source,oac_no_warn] +[source] ---- asadmin> create-domain --adminport 4848 domain1 Enter admin user name[Enter to accept default]> @@ -214,7 +210,7 @@ Command create-domain executed successfully. To start the Administration Console in a browser, enter the URL in the following format: -[source,oac_no_warn] +[source] ---- http://hostname:5000 ---- @@ -239,24 +235,24 @@ To Create a Domain From a Custom Template A custom template enables you to customize the configuration of any domain that you create from the template. -1. Create a domain to use as the basis for the template. + +1. Create a domain to use as the basis for the template. For more information, see link:#ggoei[To Create a Domain]. -2. Use the `asadmin` utility or the Administration Console to configure -the domain. + -Your configuration changes will be included in the template that you -create from the domain. -3. Copy the domain's `domain.xml` file under a new name to the -as-install`/lib/templates` directory. + -A domain's `domain.xml` file is located in the domain-dir`/config` -directory. -4. In a plain text editor, edit the file that you copied to replace -with tokens values that are to be substituted when a domain is created. + -Each token is identified as `%%%`token-name`%%%`, where token-name is + +2. Use the `asadmin` utility or the Administration Console to configure the domain. +Your configuration changes will be included in the template that you create from the domain. + +3. Copy the domain's `domain.xml` file under a new name to the +as-install``/lib/templates`` directory. +A domain's `domain.xml` file is located in the domain-dir``/config`` directory. + +4. In a plain text editor, edit the file that you copied to replace +with tokens values that are to be substituted when a domain is created. +Each token is identified as `%%%token-name%%%`, where `token-name` is one of the following names::: `ADMIN_PORT`:: Represents the port number of the HTTP port or the HTTPS port for administration. This token is replaced with one of the following - values in the command to create a domain from the template: + + values in the command to create a domain from the template: * The value of the `--adminport` option * The value of the `domain.adminPort` property `CONFIG_MODEL_NAME`:: @@ -273,7 +269,7 @@ one of the following names::: `HTTP_PORT`:: Represents the port number of the port that is used to listen for HTTP requests. This token is replaced with one of the following values in - the command to create a domain from the template: + + the command to create a domain from the template: * The value of the `--instanceport` option * A value that the `create-domain` subcommand calculates from the value of the `--portbase` option @@ -281,38 +277,37 @@ one of the following names::: `HTTP_SSL_PORT`:: Represents the port number of the port that is used to listen for secure HTTP requests. This token is replaced with one of the following - values in the command to create a domain from the template: + + values in the command to create a domain from the template: * A value that the `create-domain` subcommand calculates from the value of the `--portbase` option * The value of the `http.ssl.port` property `JAVA_DEBUGGER_PORT`:: - Represents the port number of the port that is used for connections to - the + Represents the port number of the port that is used for connections to the http://docs.oracle.com/javase/8/docs/technotes/guides/jpda/architecture.html[Java - Platform Debugger Architecture (JPDA)] debugger. This token is - replaced with one of the following values in the command to create a - domain from the template: + + Platform Debugger Architecture (JPDA)] debugger. + This token is replaced with one of the following values in the command to create + a domain from the template: * A value that the `create-domain` subcommand calculates from the value of the `--portbase` option * The value of the `java.debugger.port` property `JMS_PROVIDER_PORT`:: - Represents the port number for the Java Message Service provider. This - token is replaced with one of the following values in the command to - create a domain from the template: + + Represents the port number for the Java Message Service provider. + This token is replaced with one of the following values in the command to + create a domain from the template: * A value that the `create-domain` subcommand calculates from the value of the `--portbase` option * The value of the `jms.port` property `JMX_SYSTEM_CONNECTOR_PORT`:: - Represents the port number on which the JMX connector listens. This - token is replaced with one of the following values in the command to - create a domain from the template: + + Represents the port number on which the JMX connector listens. + This token is replaced with one of the following values in the command to + create a domain from the template: * A value that the `create-domain` subcommand calculates from the value of the `--portbase` option * The value of the `domain.jmxPort` property `ORB_LISTENER_PORT`:: Represents the port number of the port that is used for IIOP connections. This token is replaced with one of the following values - in the command to create a domain from the template: + + in the command to create a domain from the template: * A value that the `create-domain` subcommand calculates from the value of the `--portbase` option * The value of the `orb.listener.port` property @@ -320,50 +315,46 @@ one of the following names::: Represents the port number of the port that is used for secure IIOP connections with client authentication. This token is replaced with one of the following values in the command to create a domain from the - template: + + template: * A value that the `create-domain` subcommand calculates from the value of the `--portbase` option * The value of the `orb.mutualauth.port` property `ORB_SSL_PORT`:: Represents the port number of the port that is used for secure IIOP connections. This token is replaced with one of the following values - in the command to create a domain from the template: + + in the command to create a domain from the template: * A value that the `create-domain` subcommand calculates from the value of the `--portbase` option * The value of the `orb.ssl.port` property `OSGI_SHELL_TELNET_PORT`:: - Represents the port number of the port that is used for connections to - the + Represents the port number of the port that is used for connections to the http://felix.apache.org/documentation/subprojects/apache-felix-remote-shell.html[Apache - Felix Remote Shell] . This shell uses the Felix shell service to + Felix Remote Shell]. This shell uses the Felix shell service to interact with the OSGi module management subsystem. This token is - replaced with one of the following values in the command to create a - domain from the template: + + replaced with one of the following values in the command to create + a domain from the template: * A value that the `create-domain` subcommand calculates from the value of the `--portbase` option * The value of the `osgi.shell.telnet.port` property `SERVER_ID`:: Represents the name of the DAS for the domain that is being created. - This token is replaced with the string `server`. + - + This token is replaced with the string `server`. ++ [TIP] ======================================================================= - For information about how these tokens are used in the default template, examine the as-install`/lib/templates/domain.xml` file. - ======================================================================= -5. Create the domain that you want to be based on a custom template. + +5. Create the domain that you want to be based on a custom template. In the command to create the domain, pass the name of file that you edited in the previous step as the `--template` option of the link:../reference-manual/create-domain.html#GSRFM00023[`create-domain`] subcommand. -6. Before starting the domain, verify that the domain's `domain.xml` -file is valid. + -Use the link:../reference-manual/verify-domain-xml.html#GSRFM00260[`verify-domain-xml`] subcommand for this -purpose. + -Information about the options for this subcommand is included in the -subcommand's help page. + +6. Before starting the domain, verify that the domain's `domain.xml` file is valid. +Use the link:../reference-manual/verify-domain-xml.html#GSRFM00260[`verify-domain-xml`] +subcommand for this purpose. +Information about the options for this subcommand is included in the subcommand's help page. [[GSADG820]] @@ -384,25 +375,21 @@ typing the following commands at the command line. To List Domains ^^^^^^^^^^^^^^^ -Use the `list-domains` subcommand to display a list of domains and their -statuses. If the domain directory is not specified, the contents of the -domain-root-dir, the default for which is as-install`/domains`, is -listed. If there is more than one domain, the domain name must be -specified. +Use the `list-domains` subcommand to display a list of domains and their statuses. +If the domain directory is not specified, the contents of the +domain-root-dir, the default for which is as-install`/domains`, is listed. +If there is more than one domain, the domain name must be specified. -To list domains that were created in other directories, specify the -`--domaindir` option. +To list domains that were created in other directories, specify the `--domaindir` option. List domains by using the link:../reference-manual/list-domains.html#GSRFM00163[`list-domains`] subcommand. [[GSADG00127]][[ggpfv]] - - Example 3-2 Listing Domains This example lists the domains in the default domain root directory: -[source,oac_no_warn] +[source] ---- asadmin> list-domains Name: domain1 Status: Running @@ -440,15 +427,12 @@ a given administrative operation without specifying any identity. A server (domain) allows administrative operations to be run using this default identity if the following conditions are true: -* The server (domain) uses file realm for authentication of -administrative users. + +* The server (domain) uses file realm for authentication of administrative users. If this condition is not true, you will need to specify the user name and password. -* The file realm has one and only one user (what the user name is does -not matter). + -If this condition is not true, you will also need to specify the user -name. -* That one user has no password. + +* The file realm has one and only one user (what the user name is does not matter). +If this condition is not true, you will also need to specify the user name. +* That one user has no password. If this condition is not true, you will need to specify the password. By default, all of these conditions are true, unless you have created @@ -467,53 +451,50 @@ and password. There is no logout subcommand. If you want to log in to another domain, invoke `asadmin login` with new values for `--host` and `--port`. -1. Determine the name of the domain that you are logging in to. + -To list the existing domains: + -[source,oac_no_warn] +1. Determine the name of the domain that you are logging in to. +To list the existing domains: ++ +[source] ---- asadmin list-domains ---- -2. Log in to the domain by using the olink:GSRFM00210[`login`] command. +2. Log in to the domain by using the olink:GSRFM00210[`login`] command. [[GSADG00128]][[ghlfx]] - - Example 3-3 Logging In To a Domain on a Remote Machine This example logs into a domain located on another machine. Options are specified before the `login` subcommand. -[source,oac_no_warn] +[source] ---- asadmin> --host foo --port 8282 login -Please enter the admin user name>admin Please enter the admin password> -Trying to authenticate for administration of server at host [foo] and port [8282] ... -Login information relevant to admin user name [admin] -for host [foo] and admin port [8282] stored at [/.asadminpass] successfully. +Please enter the admin user name>admin Please enter the admin password> +Trying to authenticate for administration of server at host [foo] and port [8282] ... +Login information relevant to admin user name [admin] +for host [foo] and admin port [8282] stored at [/.asadminpass] successfully. Make sure that this file remains protected. Information stored in this file will be used by asadmin commands to manage associated domain. ---- [[GSADG00129]][[ghldv]] - - Example 3-4 Logging In to a Domain on the Default Port of Localhost This example logs into a domain on `myhost` on the default port. Options are specified before the login subcommand. -[source,oac_no_warn] +[source] ---- -asadmin> --host myhost login +asadmin> --host myhost login Please enter the admin user name>admin -Please enter the admin password> -Trying to authenticate for administration of server at host [myhost] and port [4848] ... -An entry for login exists for host [myhost] and port [4848], probably from -an earlier login operation. -Do you want to overwrite this entry (y/n)?y -Login information relevant to admin user name [admin] for host [myhost] -and admin port [4848] stored at [/home/joe/.asadminpass] successfully. -Make sure that this file remains protected. Information stored in this file will be used by +Please enter the admin password> +Trying to authenticate for administration of server at host [myhost] and port [4848] ... +An entry for login exists for host [myhost] and port [4848], probably from +an earlier login operation. +Do you want to overwrite this entry (y/n)?y +Login information relevant to admin user name [admin] for host [myhost] +and admin port [4848] stored at [/home/joe/.asadminpass] successfully. +Make sure that this file remains protected. Information stored in this file will be used by asadmin commands to manage associated domain. ---- @@ -541,23 +522,18 @@ Before You Begin A domain must be stopped before it can be deleted. -1. List domains by using the link:../reference-manual/list-domains.html#GSRFM00163[`list-domains`] -subcommand. -2. If necessary, notify domain users that the domain is being deleted. -3. Ensure that the domain you want to delete is stopped. + -If needed, see link:#ggoch[To Stop a Domain]. -4. Delete the domain by using the link:../reference-manual/delete-domain.html#GSRFM00075[`delete-domain`] -subcommand. +1. List domains by using the link:../reference-manual/list-domains.html#GSRFM00163[`list-domains`] subcommand. +2. If necessary, notify domain users that the domain is being deleted. +3. Ensure that the domain you want to delete is stopped. If needed, see link:#ggoch[To Stop a Domain]. +4. Delete the domain by using the link:../reference-manual/delete-domain.html#GSRFM00075[`delete-domain`] subcommand. [[GSADG00130]][[ggoiy]] - - Example 3-5 Deleting a Domain This example deletes a domain named `domain1` from the location specified. -[source,oac_no_warn] +[source] ---- asadmin> delete-domain --domaindir ..\domains domain1 Domain domain1 deleted. @@ -599,7 +575,6 @@ separately. [NOTE] ======================================================================= - For Microsoft Windows, you can use an alternate method to start a domain. From the Windows Start menu, select the command for your distribution of GlassFish Server: @@ -608,7 +583,6 @@ distribution of GlassFish Server: Server > Start Admin Server. * If you are using the Web Profile, select Programs > Oracle GlassFish Server Web Profile > Start Admin Server. - ======================================================================= @@ -617,13 +591,11 @@ This subcommand is supported in local mode only. Start a domain by using the link:../reference-manual/start-domain.html#GSRFM00235[`start-domain`] subcommand. [[GSADG00131]][[ggocw]] - - Example 3-6 Starting a Domain This example starts `domain2` in the default domain directory. -[source,oac_no_warn] +[source] ---- asadmin> start-domain domain2 ---- @@ -631,9 +603,9 @@ asadmin> start-domain domain2 If there is only one domain, you can omit the domain name. If you do not include the password, you might be prompted to supply it. -[source,oac_no_warn] +[source] ---- -Name of the domain started: [domain1] and its location: +Name of the domain started: [domain1] and its location: [C:\prelude\v3_prelude_release\distributions\web\target\glassfish domains\domain1]. Admin port for the domain: [4848]. @@ -662,8 +634,7 @@ link:../reference-manual/restart-domain.html#GSRFM00218[`restart-domain`] subcom [NOTE] -======================================================================= - +==== For Microsoft Windows, you can use an alternate method to stop a domain. From the Start menu, select the command for your distribution of GlassFish Server: @@ -672,23 +643,20 @@ GlassFish Server: Server > Stop Admin Server. * If you are using the Web Profile, select Programs > Oracle GlassFish Server Web Profile > Stop Admin Server. - -======================================================================= +==== -1. If necessary, notify users that you are going to stop the domain. -2. Stop the domain by using the link:../reference-manual/stop-domain.html#GSRFM00240[`stop-domain`] +1. If necessary, notify users that you are going to stop the domain. +2. Stop the domain by using the link:../reference-manual/stop-domain.html#GSRFM00240[`stop-domain`] subcommand. [[GSADG00132]][[gioes]] - - Example 3-7 Stopping a Domain (or Server) This example stops `domain1` in the default directory, where `domain1` is the only domain present in the directory. -[source,oac_no_warn] +[source] ---- asadmin> stop-domain Waiting for the domain to stop ........... @@ -722,19 +690,15 @@ same machine. If the server will not restart, use the link:../reference-manual/stop-domain.html#GSRFM00240[`stop-domain`] subcommand followed by the link:../reference-manual/start-domain.html#GSRFM00235[`start-domain`] subcommand. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Restart the domain by using the link:../reference-manual/restart-domain.html#GSRFM00218[`restart-domain`] -subcommand. +1. Ensure that the server is running. Remote subcommands require a running server. +2. Restart the domain by using the link:../reference-manual/restart-domain.html#GSRFM00218[`restart-domain`] subcommand. [[GSADG00133]][[ggoet]] - - Example 3-8 Restarting a Domain (or Server) This example restarts `mydoimain4` in the default directory. -[source,oac_no_warn] +[source] ---- asadmin> restart-domain mydomain4 Waiting for the domain to restart ........... @@ -742,13 +706,11 @@ Command restart-domain executed successfully. ---- [[GSADG00134]][[giupx]] - - Example 3-9 Restarting a Domain in a Browser This example invokes the `restart-domain` subcommand in a browser. -[source,oac_no_warn] +[source] ---- http://yourhost:4848/__asadmin/restart-domain ---- @@ -780,14 +742,10 @@ must prevent service shutdown when a user logs out. The following topics are addressed here: -* link:#gjzfg[To Configure a DAS or an Instance for Automatic Restart on -Windows] -* link:#giurs[To Configure a DAS or an Instance for Automatic Restart on -Linux] -* link:#giusi[To Configure a DAS or an Instance for Automatic Restart on -Oracle Solaris] -* link:#giurf[To Prevent Service Shutdown When a User Logs Out on -Windows] +* link:#gjzfg[To Configure a DAS or an Instance for Automatic Restart on Windows] +* link:#giurs[To Configure a DAS or an Instance for Automatic Restart on Linux] +* link:#giusi[To Configure a DAS or an Instance for Automatic Restart on Oracle Solaris] +* link:#giurf[To Prevent Service Shutdown When a User Logs Out on Windows] [[gjzfg]][[GSADG00338]][[to-configure-a-das-or-an-instance-for-automatic-restart-on-windows]] @@ -803,13 +761,15 @@ the Windows command line, use the `sc.exe` tool. This subcommand must be run as the OS-level administrator user. -1. Create the service by using the link:../reference-manual/create-service.html#GSRFM00057[`create-service`] +1. Create the service by using the link:../reference-manual/create-service.html#GSRFM00057[`create-service`] subcommand. -2. After the service is created, start the service by using the Windows -Services Manager or the Windows Services Wrapper. + +2. After the service is created, start the service by using the Windows +Services Manager or the Windows Services Wrapper. ++ For example, to start the service for the default domain by using the -`sc.exe` tool, type: + -[source,oac_no_warn] +`sc.exe` tool, type: ++ +[source] ---- C:\> sc start domain1 ---- @@ -820,19 +780,17 @@ tool as follows: * To uninstall the service, use the `sc delete` command. [[GSADG00135]][[gjzix]] - - Example 3-10 Creating a Service to Restart a DAS Automatically on Windows This example creates a service for the default domain on a system that is running Windows. -[source,oac_no_warn] +[source] ---- asadmin> create-service Found the Windows Service and successfully uninstalled it. -The Windows Service was created successfully. It is ready to be started. Here are +The Windows Service was created successfully. It is ready to be started. Here are the details: ID of the service: domain1 Display Name of the service:domain1 GlassFish Server @@ -848,21 +806,19 @@ uninstall Install Command: C:\glassfishv3\glassfish\domains\domain1\bin\domain1Service.exe install -This message is also available in a file named PlatformServices.log in the domain's +This message is also available in a file named PlatformServices.log in the domain's root directory Command create-service executed successfully. ---- [[GSADG00136]][[gktso]] - - Example 3-11 Querying the Service to Restart a DAS Automatically on Windows This obtains information about the service for the default domain on a system that is running Windows. -[source,oac_no_warn] +[source] ---- C:\> sc query domain1 @@ -904,14 +860,12 @@ Create the service by using the link:../reference-manual/create-service.html#GSR subcommand. [[GSADG828]][[sthref19]] - - Example 3-12 Creating a Service to Restart a DAS Automatically on Linux This example creates a service for the default domain on a system that is running Linux. -[source,oac_no_warn] +[source] ---- asadmin> create-service Found the Linux Service and successfully uninstalled it. @@ -927,7 +881,7 @@ Here are the most typical Linux commands of interest: * /etc/init.d/GlassFish_domain1 stop * /etc/init.d/GlassFish_domain1 restart -For your convenience this message has also been saved to this file: +For your convenience this message has also been saved to this file: /export/glassfish3/glassfish/domains/domain1/PlatformServices.log Command create-service executed successfully. ---- @@ -979,26 +933,26 @@ If a particular GlassFish Server domain or instance should not have default user privileges, modify the manifest of the service and reimport the service. -1. Create the service by using the link:../reference-manual/create-service.html#GSRFM00057[`create-service`] +1. Create the service by using the link:../reference-manual/create-service.html#GSRFM00057[`create-service`] subcommand. -2. After the service is created, enable the service by using the -`svacdm enable` command. + -For example, to enable the SMF service for the default domain, type: + -[source,oac_no_warn] +2. After the service is created, enable the service by using the +`svacdm enable` command. ++ +For example, to enable the SMF service for the default domain, type: ++ +[source] ---- svacdm enable /appserver/domains/domain1 ---- [[GSADG00137]][[giuqp]] - - Example 3-13 Creating a Service to Restart a Domain Automatically on Oracle Solaris This example creates a service for the default domain on a system that is running Oracle Solaris. -[source,oac_no_warn] +[source] ---- asadmin> create-service The Service was created successfully. Here are the details: @@ -1052,32 +1006,33 @@ prevent the service from shutting down when a user logs out, you must set the `-Xrs` Java VM option (`https://javaee.github.io/glassfish/documentation`). -1. Ensure that the DAS is running. -2. Set the `-Xrs` Java VM option for the DAS. + -Use the link:../reference-manual/create-jvm-options.html#GSRFM00042[`create-jvm-options`] subcommand for this -purpose. + -[source,oac_no_warn] +1. Ensure that the DAS is running. + +2. Set the `-Xrs` Java VM option for the DAS. +Use the link:../reference-manual/create-jvm-options.html#GSRFM00042[`create-jvm-options`] subcommand for this purpose. ++ +[source] ---- asadmin> create-jvm-options -Xrs ---- -3. Set the `-Xrs` Java VM option for the Java VM within which the -`asadmin` utility runs. + + +3. Set the `-Xrs` Java VM option for the Java VM within which the `asadmin` utility runs. To set this option, edit the `asadmin.bat` file to add the `-Xrs` option to the line that runs the `admin-cli.jar` file. -1. In the as-install`\bin\asadmin.bat` file, edit the line to read as -follows: + -[source,oac_no_warn] +.. In the as-install``\bin\asadmin.bat`` file, edit the line to read as follows: ++ +[source] ---- %JAVA% -Xrs -jar "%~dp0..\modules\admin-cli.jar" %* ---- -2. In the as-install-parent`\bin\asadmin.bat` file, edit the line to -read as follows: + -[source,oac_no_warn] +.. In the as-install-parent``\bin\asadmin.bat`` file, edit the line to read as follows: ++ +[source] ---- %JAVA% -Xrs -jar "%~dp0..\glassfish\modules\admin-cli.jar" %* ---- -4. If the GlassFish Server service is running, restart the service for -your changes to take effect. + +4. If the GlassFish Server service is running, restart the service for your changes to take effect. [[gityo]][[GSADG00541]][[backing-up-and-restoring-a-domain]] @@ -1111,22 +1066,22 @@ instead of the default domain-root-dir`/`domain-dir`/backups`. * `--description` to provide a description of the backup to be stored in the backup itself. -1. Ensure that the domain is stopped . + +1. Ensure that the domain is stopped . ++ The `backup-domain` subcommand operates only when the domain is stopped. -2. Back up the domain by using the link:../reference-manual/backup-domain.html#GSRFM00003[`backup-domain`] +2. Back up the domain by using the link:../reference-manual/backup-domain.html#GSRFM00003[`backup-domain`] subcommand. -3. Restore the domain to its previous state, if necessary. + +3. Restore the domain to its previous state, if necessary. ++ Start or resume the domain. [[GSADG00149]][[ggoxt]] - - Example 3-14 Backing Up the Default Domain This example makes a backup of the default domain, `domain1`, storing the backup file in `/net/backups.example.com/glassfish`: -[source,oac_no_warn] +[source] ---- asadmin> backup-domain --backupdir /net/backups.example.com/glassfish domain1 Backed up domain1 at Mon Jan 17 08:16:22 PST 2011. @@ -1154,31 +1109,32 @@ The `restore-domain` subcommand can use backup files created by the full backups and configuration-only backups. Automatic backup configurations are available only in Oracle GlassFish Server. -1. If necessary, notify domain users that the domain is being restored +1. If necessary, notify domain users that the domain is being restored from backup. -2. Ensure that the domain is stopped. + +2. Ensure that the domain is stopped. ++ The `restore-domain` subcommand operates only when the domain is -stopped. + +stopped. ++ To determine whether the domain is running, use the link:../reference-manual/list-domains.html#GSRFM00163[`list-domains`] subcommand, as described in -link:#ggoco[To List Domains]. + +link:#ggoco[To List Domains]. ++ To stop the domain, use the link:../reference-manual/stop-domain.html#GSRFM00240[`stop-domain`] subcommand as described in link:#ggoch[To Stop a Domain]. -3. Restore backup files for a domain by using the +3. Restore backup files for a domain by using the link:../reference-manual/restore-domain.html#GSRFM00221[`restore-domain`] subcommand. -4. Verify that the restore has succeeded. -5. If necessary, notify users that the domain has been restored and is +4. Verify that the restore has succeeded. +5. If necessary, notify users that the domain has been restored and is available. [[GSADG00150]][[ggoys]] - - Example 3-15 Restoring the Default Domain This example restores files for the default domain, `domain1`, from the most recent backup stored in a specified backup directory: -[source,oac_no_warn] +[source] ---- asadmin> restore-domain --backupdir /net/backups.example.com/glassfish domain1 Restored the domain (domain1) to /home/user1/glassfish3/glassfish/domains/domain1 @@ -1208,14 +1164,12 @@ backups are stored instead of the default domain-dir`/backups`. List backups by using the `list-backups` subcommand. [[GSADG00151]][[ghgsv]] - - Example 3-16 Listing Backups of the Default Domain This example lists the backups of the default domain, `domain1`, that are stored in the `/net/backups.example.com/glassfish` directory: -[source,oac_no_warn] +[source] ---- asadmin> list-backups --backupdir /net/backups.example.com/glassfish domain1 CONFIG USER BACKUP DATE FILENAME @@ -1254,26 +1208,22 @@ situation where the first host crashes or is being taken out of service. [NOTE] -======================================================================= - +==== You must maintain a backup of the DAS from the first host using the olink:GSRFM00003[`backup-domain`] subcommand as described in link:#ggocq[To Back Up a Domain]. You can automatically maintain a backup of the DAS using the automatic backups feature of Oracle GlassFish Server. - -======================================================================= +==== [NOTE] -======================================================================= - +==== Oracle GlassFish Server includes `asadmin` subcommands that simplify this procedure. If you are using Oracle GlassFish Server, see link:#gglnp[To Migrate the DAS]. - -======================================================================= +==== [[gglnp]][[GSADG00355]][[to-migrate-the-das]] @@ -1284,62 +1234,63 @@ To Migrate the DAS The following steps are required to migrate the DAS from the first host (olddashost) to the third host (newdashost). -1. Install GlassFish Server on newdashost just as it was installed on -olddashost. + -This is required so that the DAS can be properly restored on newdashost -without causing path conflicts. -2. Use the `restore-domain` subcommand to restore the latest backup -file onto newdashost. + -For example: + -[source,oac_no_warn] +1. Install GlassFish Server on newdashost just as it was installed on olddashost. +This is required so that the DAS can be properly restored on newdashost without causing path conflicts. + +2. Use the `restore-domain` subcommand to restore the latest backup file onto newdashost. +For example: ++ +[source] ---- asadmin> restore-domain --backupdir /net/backups.example.com/glassfish ---- -This example assumes that backups are stored in a network-accessible -location. If this is not the case, manually copy the latest backup file -from offline storage to a directory on newdashost. + +This example assumes that backups are stored in a network-accessible location. +If this is not the case, manually copy the latest backup file +from offline storage to a directory on newdashost. You can backup any domain. However, while re-creating the domain, the domain name should be same as the original. -3. Stop the domain on olddashost, if it is running. -4. Start the domain on newdashost by using the -link:../reference-manual/start-domain.html#GSRFM00235[`start-domain`] subcommand. + -For example: + -[source,oac_no_warn] + +3. Stop the domain on olddashost, if it is running. + +4. Start the domain on newdashost by using the +link:../reference-manual/start-domain.html#GSRFM00235[`start-domain`] subcommand. +For example: ++ +[source] ---- asadmin> start-domain domain1 ---- -5. If the domain on olddashost was centrally administered, set up -centralized administration on newdashost. + -See "link:../ha-administration-guide/ssh-setup.html#GSHAG00003[Enabling Centralized Administration of GlassFish -Server Instances]" in GlassFish Server Open Source Edition High -Availability Administration Guide for instructions. -6. Verify that instances on other hosts are visible to the new DAS on -newdashost: + -[source,oac_no_warn] + +5. If the domain on olddashost was centrally administered, set up +centralized administration on newdashost. +See "link:../ha-administration-guide/ssh-setup.html#GSHAG00003[Enabling Centralized Administration of GlassFish Server Instances]" +in GlassFish Server Open Source Edition High Availability Administration Guide for instructions. + +6. Verify that instances on other hosts are visible to the new DAS on newdashost: ++ +[source] ---- asadmin> list-instances --long ---- -7. Change the DAS host values for properties under the node on apphost. + -In the file as-install`/nodes/`node-name`/agent/config/das.properties` +7. Change the DAS host values for properties under the node on apphost. +In the file as-install``/nodes/``node-name``/agent/config/das.properties`` file, change the `agent.das.host` property value to refer to newdashost instead of olddasnost. -8. Use the new DAS to restart clusters and standalone instances on -apphost: + + +8. Use the new DAS to restart clusters and standalone instances on apphost: Restarting the clustered and standalone instances on apphost triggers their recognition of the new DAS on newdashost. -1. Use the `list-clusters` subcommand to list the clusters in the -domain. -2. Use the `stop-cluster` subcommand to stop each cluster. -3. Use the `list-instances` subcommand to list the instances in the -domain. -4. Use the `restart-instance` subcommand to restart each standalone -instance. -5. Use the `start-cluster` subcommand to start each cluster. + -If the domain does not use centralized administration, use the -`start-local-instance` subcommand to start the cluster instances on -apphost. -9. Verify that instances on apphost are running: + -[source,oac_no_warn] +.. Use the `list-clusters` subcommand to list the clusters in the domain. +.. Use the `stop-cluster` subcommand to stop each cluster. +.. Use the `list-instances` subcommand to list the instances in the domain. +.. Use the `restart-instance` subcommand to restart each standalone instance. +.. Use the `start-cluster` subcommand to start each cluster. + If the domain does not use centralized administration, use the + `start-local-instance` subcommand to start the cluster instances on apphost. + +9. Verify that instances on apphost are running: ++ +[source] ---- asadmin> list-instances --long ---- @@ -1365,18 +1316,15 @@ Use the `uptime` subcommand in remote mode to display the length of time that the domain administration server (DAS) has been running since it was last started. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Display uptime by using the link:../reference-manual/uptime.html#GSRFM00258[`uptime`] subcommand. +1. Ensure that the server is running. Remote subcommands require a running server. +2. Display uptime by using the link:../reference-manual/uptime.html#GSRFM00258[`uptime`] subcommand. [[GSADG00152]][[ghlds]] - - Example 3-17 Displaying the DAS Uptime This example displays the length of time that the DAS has been running. -[source,oac_no_warn] +[source] ---- asadmin> uptime Uptime: 1 Weeks, 4 days, 0 hours, 17 minutes, 14 seconds, Total milliseconds: 951434595 @@ -1398,38 +1346,37 @@ To Switch a Domain to Another Supported Java Version GlassFish Server 5.0 requires Java SE 8 as the underlying virtual machine for the Java platform (Java Virtual Machine or JVM machine). - [NOTE] ======================================================================= - Do not downgrade to an earlier Java version after a domain has been created with a newer JVM machine. If you must downgrade your JVM machine, downgrade it only for individual domains. - ======================================================================= - -1. If you have not already done so, download the desired Java SDK (not -the JRE) and install it on your system. + +1. If you have not already done so, download the desired Java SDK (not the JRE) and install it on your system. The Java SDK can be downloaded from the -http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java -SE Downloads page] . -2. Start the domain for which you are changing the JDK. + -Use the following format: + -[source,oac_no_warn] +http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java SE Downloads page] . + +2. Start the domain for which you are changing the JDK. +Use the following format: ++ +[source] ---- as-install/bin/asadmin start-domain domain-name ---- -For a valid JVM installation, locations are checked in the following -order: -1. `domain.xml` (`java-home` inside `java-config`) -2. `asenv.conf` (setting `AS_JAVA="path to java home"`) + -If a legal JDK is not found, a fatal error occurs and the problem is -reported back to you. -3. If necessary, change the JVM machine attributes for the domain. + + +For a valid JVM installation, locations are checked in the following order: + +1. `domain.xml` (`java-home` inside `java-config`) + +2. `asenv.conf` (setting `AS_JAVA="path to java home"`) +If a legal JDK is not found, a fatal error occurs and the problem is reported back to you. + +3. If necessary, change the JVM machine attributes for the domain. In particular, you might need to change the `JAVA_HOME` environment -variable. For example, to change the `JAVA_HOME` variable, type: + -[source,oac_no_warn] +variable. For example, to change the `JAVA_HOME` variable, type: ++ +[source] ---- as-install/bin/asadmin set "server.java-config.java-home=path-to-java-home" ---- @@ -1448,47 +1395,43 @@ link:../reference-manual/create-domain.html#GSRFM00023[`create-domain`] subcomma If this port must be reallocated for another purpose, change the port on which the DAS listens for administration requests. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Set the port number to its new value. + -Use the link:../reference-manual/set.html#GSRFM00226[`set`] subcommand for this purpose. + -[source,oac_no_warn] +1. Ensure that the server is running. Remote subcommands require a running server. +2. Set the port number to its new value. +Use the link:../reference-manual/set.html#GSRFM00226[`set`] subcommand for this purpose. ++ +[source] ---- -$ asadmin set +$ asadmin set server-config.network-config.network-listeners.network-listener.admin-listener.port=new-port-number ---- The new-port-number is the new value that you are setting for the port -number. + - +number. ++ [NOTE] ======================================================================= - After you set the port number to its new value, running the `list-domains` subcommand incorrectly reports that the DAS is not running. The `list-domains` subcommand reports the correct state again only after you stop and restart the domain as explained in the steps that follow. - ======================================================================= -3. Stop the domain, specifying the host on which the DAS is running and -the old administration port number of the domain. + +3. Stop the domain, specifying the host on which the DAS is running and +the old administration port number of the domain. You must specify the old port number because the DAS is still listening for administration requests on this port. If you omit the port number, the command fails because the `stop-domain` subcommand attempts to -contact the DAS through the new port number. + - +contact the DAS through the new port number. ++ [NOTE] ======================================================================= - Only the options that are required to complete this task are provided in this step. For information about all the options for controlling the behavior of the domain, see the olink:GSRFM00240[`stop-domain`(1)] help page. - ======================================================================= - -[source,oac_no_warn] ++ +[source] ---- $ asadmin --host host-name --port old-port-number stop-domain ---- @@ -1500,19 +1443,18 @@ host-name:: old-port-number:: The value of administration port number of the domain before you changed it in the preceding step. -4. Start the domain. + +4. Start the domain. ++ [NOTE] ======================================================================= - Only the options that are required to complete this task are provided in this step. For information about all the options for controlling the behavior of the domain, see the olink:GSRFM00235[`start-domain`(1)] help page. - ======================================================================= - -[source,oac_no_warn] ++ +[source] ---- $ start-domain [domain-name] ---- @@ -1521,16 +1463,14 @@ subdirectory is contained in the `domains` directory, you may omit this option. [[GSADG00153]][[gkvkl]] - - Example 3-18 Changing the Administration Port of a Domain This example changes the administration port of the domain `domain1` from 4848 to 4849. The DAS is running on the host `xk01.example.com`. -[source,oac_no_warn] +[source] ---- -$ asadmin set +$ asadmin set server-config.network-config.network-listeners.network-listener.admin-listener.port=4849 server-config.network-config.network-listeners.network-listener.admin-listener.port=4849 Command set executed successfully. diff --git a/docs/administration-guide/src/main/jbake/content/general-administration.adoc b/docs/administration-guide/src/main/jbake/content/general-administration.adoc index 20f66cfc3b34..ad382c1aab58 100644 --- a/docs/administration-guide/src/main/jbake/content/general-administration.adoc +++ b/docs/administration-guide/src/main/jbake/content/general-administration.adoc @@ -4,6 +4,7 @@ title=General Administration next=domains.html prev=part-runtime-admin.html ~~~~~~ + General Administration ====================== @@ -68,7 +69,7 @@ directory is in your path. The syntax for running the `asadmin` utility is as follows: -[source,oac_no_warn] +[source] ---- asadmin [asadmin-util-options] [subcommand [subcommand-options] [operands]] ---- @@ -109,7 +110,7 @@ subcommands. Options are case-sensitive. The `asadmin` utility has the following types of options: -* `asadmin`utility options. These options control the behavior of the +* `asadmin` utility options. These options control the behavior of the `asadmin` utility, not the subcommand. The `asadmin` utility options may precede or follow the subcommand, but `asadmin` utility options after the subcommand are deprecated. All `asadmin` utility options must either @@ -122,17 +123,16 @@ subcommand, not the `asadmin` utility. Subcommand options must follow the subcommand. For a description of a subcommand's options, see the entry for the subcommand in the https://javaee.github.io/glassfish/doc/5.0/reference-manual.pdf[GlassFish -Server Open Source Edition Reference Manual]. + +Server Open Source Edition Reference Manual]. ++ [NOTE] -======================================================================= - +==== Not all subcommand options are supported for this release of GlassFish Server. If you specify an unsupported option, a syntax error does not occur. Instead, the command runs successfully and the unsupported option is silently ignored. - -======================================================================= +==== A subcommand option may have the same name as an `asadmin` utility @@ -178,14 +178,12 @@ run. If you require the same `asadmin` utility options for multiple subcommands, use the `asadmin` utility in multimode. For more information, see link:#giodz[To Start a Multimode Session]. -1. In the operating system's command shell, run the `asadmin` utility, +1. In the operating system's command shell, run the `asadmin` utility, specifying the subcommand. -2. If necessary, also specify any required `asadmin` utility options, +2. If necessary, also specify any required `asadmin` utility options, subcommand options, and operands. [[GSADG00098]][[giwdr]] - - Example 2-1 Running an `asadmin` Utility Subcommand in Single Mode This example runs the link:../reference-manual/list-applications.html#GSRFM00148[`list-applications`] subcommand @@ -195,7 +193,7 @@ used. The example shows that the application `hello` is deployed on the local host. -[source,oac_no_warn] +[source] ---- asadmin list-applications hello @@ -203,8 +201,6 @@ Command list-applications executed successfully. ---- [[GSADG00099]][[giwbf]] - - Example 2-2 Specifying an `asadmin` Utility Option With a Subcommand in Single Mode @@ -216,7 +212,7 @@ The example shows that the applications `basic-ezcomp`, `scrumtoys`, `ejb31-war`, and `automatic-timer-ejb` are deployed on the host `srvr1.example.com`. -[source,oac_no_warn] +[source] ---- asadmin --host srvr1.example.com list-applications basic-ezcomp @@ -227,8 +223,6 @@ Command list-applications executed successfully. ---- [[GSADG00100]][[ghvyk]] - - Example 2-3 Specifying an `asadmin` Utility Option and a Subcommand Option in Single Mode @@ -237,7 +231,7 @@ This example specifies the `--host` `asadmin` utility option and the single mode. In this example, the DAS is running on the host `srvr1.example.com` and applications of type `web` are to be listed. -[source,oac_no_warn] +[source] ---- asadmin --host srvr1.example.com list-applications --type web basic-ezcomp @@ -257,36 +251,34 @@ information is written in the style of UNIX platform man pages. This help information is also available in the link:../reference-manual/toc.html#GSRFM[GlassFish Server Open Source Edition Reference Manual]. -1. If you are displaying help information for a remote subcommand, -ensure that the server is running. + +1. If you are displaying help information for a remote subcommand, +ensure that the server is running. ++ Remote subcommands require a running server. -2. Specify the subcommand of interest as the operand of the `help` -subcommand. + +2. Specify the subcommand of interest as the operand of the `help` +subcommand. ++ If you run the `help` subcommand without an operand, help information for the `asadmin` utility is displayed. [[GSADG00101]][[giwgs]] - - Example 2-4 Displaying Help Information for the `asadmin` Utility This example displays the help information for the `asadmin` utility. -[source,oac_no_warn] +[source] ---- asadmin help ---- [[GSADG00102]][[giusg]] - - Example 2-5 Displaying Help Information for an `asadmin` Utility Subcommand This example displays the help information for the `create-jdbc-resource` subcommand. -[source,oac_no_warn] +[source] ---- asadmin help create-jdbc-resource ---- @@ -315,45 +307,38 @@ in the session. [NOTE] -=========================================================== - +==== Starting a multimode session does not require a running DAS. +==== -=========================================================== - - -1. Do one of the following: +1. Do one of the following: * Run the `asadmin` utility without a subcommand. * Use the link:../reference-manual/multimode.html#GSRFM00213[`multimode`] subcommand. -2. If necessary, also specify any `asadmin` utility options that will +2. If necessary, also specify any `asadmin` utility options that will apply throughout the multimode session. -3. In a multimode session, the `asadmin>` prompt is displayed on the +3. In a multimode session, the `asadmin>` prompt is displayed on the command line. You can now type `asadmin` subcommands at this prompt to administer GlassFish Server. [[GSADG00103]][[givuq]] - - Example 2-6 Starting a Multimode Session With `asadmin` Utility Options This example starts a multimode session in which the `asadmin` utility options `--user` and `--passwordfile` are set for the session. -[source,oac_no_warn] +[source] ---- asadmin --user admin1 --passwordfile pwd.txt multimode ---- [[GSADG00104]][[giwgh]] - - Example 2-7 Starting a Multimode Session by Using the `multimode` Subcommand This example uses the `multimode` subcommand to start a multimode session in which the default `asadmin` utility options are used. -[source,oac_no_warn] +[source] ---- asadmin multimode ---- @@ -361,14 +346,12 @@ asadmin multimode The `asadmin>` prompt is displayed on the command line. [[GSADG00105]][[ghvzc]] - - Example 2-8 Running a Subcommand in a Multimode Session This example starts a multimode session and runs the `list-domains` subcommand in the session. -[source,oac_no_warn] +[source] ---- asadmin Enter commands one per "line", ^D to quit @@ -409,13 +392,11 @@ combinations: [CAUTION] -======================================================================= - +==== Do not type Ctrl-C to end a multimode session. If a domain or GlassFish Server instance is started from the multimode session, typing Ctrl-C kills the domain or instance process. - -======================================================================= +==== You are returned to the operating system's command shell and the @@ -432,16 +413,15 @@ To Run a Set of `asadmin` Subcommands From a File Running a set of `asadmin` subcommands from a file enables you to automate repetitive tasks. -1. Create a plain text file that contains the sequence of subcommands +1. Create a plain text file that contains the sequence of subcommands that you want to run. -2. Run the link:../reference-manual/multimode.html#GSRFM00213[`multimode`] subcommand, specifying the -file that you created. + +2. Run the link:../reference-manual/multimode.html#GSRFM00213[`multimode`] subcommand, specifying the +file that you created. ++ If necessary, also specify any `asadmin` utility options that are required to enable subcommands in the file to run. [[GSADG00106]][[givul]] - - Example 2-9 Running a Set of `asadmin` Subcommands From a File This example contains the following: @@ -453,15 +433,15 @@ a sequence of `asadmin` subcommands The `commands_file.txt` file contains the `asadmin` utility subcommands to perform the following sequence of operations: -1. Creating the domain `customdomain` -2. Starting the domain `customdomain` -3. Listing all available subcommands -4. Stopping the domain `customdomain` -5. Deleting the domain `customdomain` +1. Creating the domain `customdomain` +2. Starting the domain `customdomain` +3. Listing all available subcommands +4. Stopping the domain `customdomain` +5. Deleting the domain `customdomain` The content of the `commands_file.txt` file is as follows: -[source,oac_no_warn] +[source] ---- create-domain --portbase 9000 customdomain start-domain customdomain @@ -475,7 +455,7 @@ file. Because the `--portbase` option is specified for the `create-domain` subcommand in the file, the `--port` `asadmin` utility option must also be set. -[source,oac_no_warn] +[source] ---- asadmin --port 9048 multimode --file commands_file.txt ---- @@ -505,20 +485,16 @@ You can use the `--detach` option of the `asadmin` utility to detach enables you to run several independent subcommands from one console or script. -1. Ensure that the server is running. + -Remote commands require a running server. -2. Detach and run the subcommand by using the `asadmin` `--detach` -option. +1. Ensure that the server is running. Remote commands require a running server. +2. Detach and run the subcommand by using the `asadmin` `--detach` option. [[GSADG1056]][[sthref7]] - - Example 2-10 Using the `--detach` Option in Single Mode This example uses the `asadmin` `--detach` option in single mode to run the `create-cluster` subcommand. -[source,oac_no_warn] +[source] ---- asadmin --detach create-cluster Cluster1 Job ID: 1 @@ -526,14 +502,12 @@ Command create-cluster started successfully. ---- [[GSADG1057]][[sthref8]] - - Example 2-11 Using the `--detach` Option in Multimode This example uses the `asadmin` `--detach` option in multimode to run the `create-cluster` subcommand. -[source,oac_no_warn] +[source] ---- asadmin> create-cluster Cluster1 --detach Job ID: 1 @@ -548,14 +522,12 @@ subcommand to reattach to a job and view its status, and the about jobs is kept. [[GSADG1058]][[sthref9]] - - Example 2-12 Listing Jobs This example runs the `list-jobs` subcommand in multimode to list jobs and job information. -[source,oac_no_warn] +[source] ---- asadmin> list-jobs JOB ID COMMAND STATE EXIT CODE TIME OF COMPLETION @@ -565,8 +537,6 @@ Command list-jobs executed successfully ---- [[GSADG1059]][[sthref10]] - - Example 2-13 Attaching to a Subcommand and Checking Its Status This example runs the `attach` subcommand in multimode to attach to the @@ -574,7 +544,7 @@ This example runs the `attach` subcommand in multimode to attach to the still in progress, the output displays the current status, such as percentage complete. -[source,oac_no_warn] +[source] ---- asadmin> attach 1 Command create-cluster executed with status SUCCESS. @@ -582,15 +552,13 @@ Command attach executed successfully. ---- [[GSADG1060]][[sthref11]] - - Example 2-14 Configuring Managed Jobs This example runs the `configure-managed-jobs` subcommand in multimode to set the job retention period to 36 hours. Time periods can be specified in Hh|Mm|Ss for hours, minutes, or seconds. -[source,oac_no_warn] +[source] ---- asadmin> configure-managed-jobs --job-retention-period=36h Command configure-managed-jobs executed successfully. @@ -632,22 +600,20 @@ or update one or more system properties of the domain or configuration. Any configuration attribute can be overwritten through a system property of the corresponding name. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create system properties by using the -link:../reference-manual/create-system-properties.html#GSRFM00059[`create-system-properties`] subcommand. + +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create system properties by using the +link:../reference-manual/create-system-properties.html#GSRFM00059[`create-system-properties`] subcommand. ++ Information about properties for the subcommand is included in this help page. [[GSADG00107]][[ggovp]] - - Example 2-15 Creating a System Property This example creates a system property associated with `http-listener-port=1088` on `localhost`. -[source,oac_no_warn] +[source] ---- asadmin> create-system-properties http-listener-port=1088 Command create-system-properties executed successfully. @@ -669,21 +635,19 @@ Use the `list-system-properties` subcommand in remote mode to list the system properties that apply to a domain, cluster, or server instance or configuration. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List system properties by using the -link:../reference-manual/list-system-properties.html#GSRFM00203[`list-system-properties`] subcommand. + +1. Ensure that the server is running. Remote subcommands require a running server. +2. List system properties by using the +link:../reference-manual/list-system-properties.html#GSRFM00203[`list-system-properties`] subcommand. ++ The existing system properties are displayed, including predefined properties such as `HTTP_LISTENER_PORT` and `HTTP_SSL_LISTENER_PORT`. [[GSADG00108]][[ggopn]] - - Example 2-16 Listing System Properties This example lists the system properties on host `localhost`. -[source,oac_no_warn] +[source] ---- asadmin> list-system-properties http-listener-port=1088 @@ -705,24 +669,21 @@ To Delete a System Property Use the `delete-system-property` subcommand in remote mode to delete system properties. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the existing system properties by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the existing system properties by using the link:../reference-manual/list-system-properties.html#GSRFM00203[`list-system-properties`] subcommand. -3. Delete the system property by using the +3. Delete the system property by using the link:../reference-manual/delete-system-property.html#GSRFM00110[`delete-system-property`] subcommand. -4. If necessary, notify users that the system property has been +4. If necessary, notify users that the system property has been deleted. [[GSADG00109]][[ggoph]] - - Example 2-17 Deleting a System Property This example deletes a system property named `http-listener-port` from `localhost`. -[source,oac_no_warn] +[source] ---- asadmin> delete-system-property http-listener-port Command delete-system-property executed successfully. @@ -762,21 +723,18 @@ To Add the Default Configuration of a Module to `domain.xml` Use the `create-module-config` subcommand to add the default configuration of a module to `domain.xml`. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Add the default configuration of a module to `domain.xml` by using +1. Ensure that the server is running. Remote subcommands require a running server. +2. Add the default configuration of a module to `domain.xml` by using the link:../reference-manual/create-jdbc-resource.html#GSRFM00037[`create-module-config`] subcommand. [[GSADG1098]][[sthref12]] - - Example 2-18 Adding Module Configuration to `domain.xml` This example adds the default configuration of the web container module to `domain1` in `server-config` (the default configuration). Use the `--dryrun` option to preview the configuration before it is added. -[source,oac_no_warn] +[source] ---- asadmin> create-module-config web-container Command create-module-config executed successfully. @@ -798,20 +756,17 @@ Use the `delete-module-config` subcommand to remove the configuration of a module from `domain.xml` and cause the module to use the default configuration included in the module. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Remove the configuration of a module from `domain.xml` by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Remove the configuration of a module from `domain.xml` by using the link:../reference-manual/create-jdbc-resource.html#GSRFM00037[`delete-module-config`] subcommand. [[GSADG1101]][[sthref13]] - - Example 2-19 Removing Module Configuration From `domain.xml` This example deletes the configuration of the web container module from `domain1` in `server-config` (the default configuration). -[source,oac_no_warn] +[source] ---- asadmin> delete-module-config web-container Command delete-module-config executed successfully. @@ -832,20 +787,17 @@ To Display the Current Active Configuration of a Module Use the `get-active-module-config` subcommand to display the current active configuration of a module. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Display the current active configuration of a module by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Display the current active configuration of a module by using the link:../reference-manual/create-jdbc-resource.html#GSRFM00037[`get-active-module-config`] subcommand. [[GSADG1104]][[sthref14]] - - Example 2-20 Displaying the Current Active Configuration of a Module This example displays the current active configuration of the JMS service in `server-config` (the default configuration). -[source,oac_no_warn] +[source] ---- asadmin> get-active-module-config jms-service At location: domain/configs/config[server-config] @@ -886,24 +838,23 @@ The XML file must reside in the domain-dir`/config` directory. If you specify a relative path or simply provide the name of the XML file, this subcommand will prepend domain-dir`/config` to this operand. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Add resources from an XML file by using the -link:../reference-manual/add-resources.html#GSRFM00001[`add-resources`] subcommand. + +1. Ensure that the server is running. Remote subcommands require a running server. +2. Add resources from an XML file by using the +link:../reference-manual/add-resources.html#GSRFM00001[`add-resources`] subcommand. ++ Information about properties for the subcommand is included in this help page. -3. Restart GlassFish Server. + +3. Restart GlassFish Server. ++ See link:domains.html#ginqj[To Restart a Domain]. [[GSADG00110]][[ggozc]] - - Example 2-21 Adding Resources This example creates resources using the contents of the `resource.xml` file on `localhost`. -[source,oac_no_warn] +[source] ---- asadmin> add-resources c:\tmp\resource.xml Command : JDBC resource jdbc1 created successfully. @@ -944,19 +895,16 @@ cannot communicate with the server by using the specified login (user/password) and target (host/port) information, then the local version is displayed along with a warning message. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Display the version by using the link:../reference-manual/version.html#GSRFM00261[`version`] +1. Ensure that the server is running. Remote subcommands require a running server. +2. Display the version by using the link:../reference-manual/version.html#GSRFM00261[`version`] subcommand. [[GSADG00114]][[ghjnb]] - - Example 2-22 Displaying Version Information This example displays the version of GlassFish Server on the local host. -[source,oac_no_warn] +[source] ---- asadmin> version Version = Oracle GlassFish Server 3.0.1 (build 19) @@ -979,19 +927,16 @@ Use the `list-applications` subcommand in remote mode to list the deployed Java applications. If the `--type` option is not specified, all applications are listed. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List applications by using the link:../reference-manual/list-applications.html#GSRFM00148[`list-applications`] +1. Ensure that the server is running. Remote subcommands require a running server. +2. List applications by using the link:../reference-manual/list-applications.html#GSRFM00148[`list-applications`] subcommand. [[GSADG00115]][[ggouk]] - - Example 2-23 Listing Applications This example lists the web applications on `localhost`. -[source,oac_no_warn] +[source] ---- asadmin> list-applications --type web hellojsp @@ -1013,19 +958,16 @@ To List Containers Use the `list-containers` subcommand in remote mode to list application containers. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List containers by using the link:../reference-manual/list-containers.html#GSRFM00161[`list-containers`] +1. Ensure that the server is running. Remote subcommands require a running server. +2. List containers by using the link:../reference-manual/list-containers.html#GSRFM00161[`list-containers`] subcommand. [[GSADG00116]][[ggown]] - - Example 2-24 Listing Containers This example lists the containers on `localhost`. -[source,oac_no_warn] +[source] ---- asadmin> list-containers List all known application containers @@ -1058,26 +1000,23 @@ Use the `list-modules` subcommand in remote mode to list the modules that are accessible to the GlassFish Server module subsystem. The status of each module is included. Possible statuses include NEW and READY. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List modules by using the link:../reference-manual/list-modules.html#GSRFM00185[`list-modules`] +1. Ensure that the server is running. Remote subcommands require a running server. +2. List modules by using the link:../reference-manual/list-modules.html#GSRFM00185[`list-modules`] subcommand. [[GSADG00117]][[ghlfw]] - - Example 2-25 Listing Modules This example lists the accessible modules. -[source,oac_no_warn] +[source] ---- asadmin> list-modules ---- Information similar to the following is displayed (partial output): -[source,oac_no_warn] +[source] ---- List Of Modules Module : org.glassfish.web.jstl-connector:10.0.0.b28 @@ -1121,19 +1060,16 @@ Use the `list-commands` subcommand in remote mode to list the deployed only local subcommands are listed. By default, this subcommand displays a list of local subcommands followed by a list of remote subcommands. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List subcommands by using the link:../reference-manual/list-commands.html#GSRFM00154[`list-commands`] +1. Ensure that the server is running. Remote subcommands require a running server. +2. List subcommands by using the link:../reference-manual/list-commands.html#GSRFM00154[`list-commands`] subcommand. [[GSADG00118]][[ggpdl]] - - Example 2-26 Listing Subcommands This example lists only local subcommands. -[source,oac_no_warn] +[source] ---- asadmin> list-commands --localonly create-domain @@ -1174,19 +1110,16 @@ timers owned by a specific server instance. You can use this information to decide whether to do a timer migration, or to verify that a migration has been completed successfully. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List timers by using the link:../reference-manual/list-timers.html#GSRFM00205[`list-timers`] subcommand. +1. Ensure that the server is running. Remote subcommands require a running server. +2. List timers by using the link:../reference-manual/list-timers.html#GSRFM00205[`list-timers`] subcommand. [[GSADG00119]][[giojj]] - - Example 2-27 Listing Timers This example lists the timers in a particular standalone server instance. There is one currently active timer set. -[source,oac_no_warn] +[source] ---- asadmin> list-timers server 1 @@ -1201,19 +1134,16 @@ To Show Component Status Use the `show-component-status` subcommand in remote mode to get the status (either enabled or disabled) of the specified deployed component. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Show component status by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Show component status by using the link:../reference-manual/show-component-status.html#GSRFM00232[`show-component-status`] subcommand. [[GSADG00120]][[gjhkk]] - - Example 2-28 Showing Status of a Component This example shows the status of the `MEjbApp` component. -[source,oac_no_warn] +[source] ---- asadmin> show-component-status MEjbApp Status of MEjbApp is enabled @@ -1296,24 +1226,21 @@ port:: The HTTP port or HTTPS port for administration. path:: The path to the object. The path is the dotted name of the object in - which each dot (`.`) is replaced with a slash (`/`). + + which each dot (`.`) is replaced with a slash (`/`). ++ -[width="100%",cols="100%",] -|======================================================================= -a| -Note: - -The path to a GlassFish Server instance is -`servers/server/`instance-name, where instance-name is the name of the -instance. For the DAS, instance-name is `server` and the path is -`servers/server/server`. +[NOTE] +==== +The path to a GlassFish Server instance is ``servers/server/``instance-name, +where instance-name is the name of the instance. +For the DAS, instance-name is `server` and the path is `servers/server/server`. +==== -|======================================================================= +For more information, see the following documentation: - For more information, see the following documentation: + - * The link:../reference-manual/dotted-names.html#GSRFM00268[`dotted-names`(5ASC)] help page - * link:monitoring.html#ghbaz[How the Monitoring Tree Structure Works] - * link:overview.html#giusb[How Dotted Names Work for Configuration] +* The link:../reference-manual/dotted-names.html#GSRFM00268[`dotted-names`(5ASC)] help page +* link:monitoring.html#ghbaz[How the Monitoring Tree Structure Works] +* link:overview.html#giusb[How Dotted Names Work for Configuration] If the URL to a REST resource for GlassFish Server monitoring or configuration data is opened in a web browser, the browser displays a @@ -1338,8 +1265,7 @@ managing a domain. .*Figure 2-1 Web Page for the REST Resource for Managing a Domain* image:img/rest-management.png[ -"Screen capture showing the web page for the REST resource for managing a -domain."] +"Screen capture showing the web page for the REST resource for managing a domain."] [[gkwib]][[GSADG00635]][[rest-urls-for-accessing-the-log-file]] @@ -1419,8 +1345,7 @@ supports |`GET` [NOTE] -======================================================================= - +==== REST requests that add, update, or delete objects must specify the `X-Requested-By` header with the value `GlassFish REST HTML interface`. @@ -1428,8 +1353,7 @@ The `GET` method determines the methods and method parameters that an object in the tree supports and provides additional information about the object. For details, see link:#gjjel[To Retrieve Data for an Object in the Tree]. - -======================================================================= +==== [[gjjei]][[GSADG00324]][[to-determine-the-methods-and-method-parameters-that-an-object-in-the-tree-supports]] @@ -1454,30 +1378,28 @@ Configuration Objects]. [NOTE] -======================================================================= - +==== Each `POST` method and `DELETE` method that a REST resource supports has an equivalent `asadmin` subcommand. The parameters of a `POST` method or a `DELETE` method correspond to the options of the method's equivalent `asadmin` subcommand. For information about the options of `asadmin` subcommand, see the olink:GSRFM[GlassFish Server Open Source Edition Reference Manual]. - -======================================================================= +==== -1. Ensure that the server is running. + +1. Ensure that the server is running. ++ Operations on REST resources for GlassFish Server data require a running server. -2. Use the `GET` method on the REST resource that represents the -object. + +2. Use the `GET` method on the REST resource that represents the +object. ++ The `GET` method returns the list of methods that the resource supports. For each method, the list of acceptable message parameters or the list of acceptable query parameters are returned. [[GSADG00121]][[gjjdi]] - - Example 2-29 Determining the Methods and Method Parameters That an Object in the Tree Supports @@ -1495,7 +1417,7 @@ the `POST` method. Line breaks and white space are added to enhance readability. -[source,oac_no_warn] +[source] ---- curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/nodes/node/sj01 { @@ -1554,15 +1476,14 @@ You can specify the format in which this information is presented. For more information, see link:#gjijz[Formats for Resource Representation of Configuration Objects]. -1. Ensure that the server is running. + +1. Ensure that the server is running. ++ Operations on REST resources for GlassFish Server data require a running server. -2. Use the `GET` method on the REST resource that represents the +2. Use the `GET` method on the REST resource that represents the object. [[GSADG00122]][[gjjed]] - - Example 2-30 Retrieving Data for an Object in the Tree This example uses the cURL utility to retrieve data for the resource for @@ -1578,7 +1499,7 @@ for administration is 4848. Line breaks and white space are added to enhance readability. -[source,oac_no_warn] +[source] ---- curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/nodes/node/sj01 { @@ -1626,24 +1547,25 @@ curl -X GET -H "Accept: application/json" http://localhost:4848/management/domai To Add an Object to the Tree ++++++++++++++++++++++++++++ -1. Ensure that the server is running. + +1. Ensure that the server is running. ++ Operations on REST resources for GlassFish Server data require a running server. -2. Determine the acceptable message parameters for the `POST` method of -the resource that represents the parent of the object. + +2. Determine the acceptable message parameters for the `POST` method of +the resource that represents the parent of the object. ++ For information about how to perform this step, see link:#gjjei[To Determine the Methods and Method Parameters That an Object in the Tree Supports]. -3. Use the `POST` method on the REST resource that represents the +3. Use the `POST` method on the REST resource that represents the parent of the object that you are adding. -4. Confirm that the object has been added. + +4. Confirm that the object has been added. ++ Perform this step on the resource that represents the object that you have just added, not the parent. For information about how to perform this step, see link:#gjjel[To Retrieve Data for an Object in the Tree]. [[GSADG00123]][[gjjen]] - - Example 2-31 Adding an Object to the Tree This example uses the cURL utility to add a JDBC resource object to the @@ -1654,11 +1576,12 @@ for administration is 4848. Line breaks are added to enhance readability. -1. This step determines the acceptable message parameters for the -`POST` method of the resource `jdbc-resource`. + -[source,oac_no_warn] +1. This step determines the acceptable message parameters for the +`POST` method of the resource `jdbc-resource`. ++ +[source] ---- -curl -X GET -H "Accept: application/json" +curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/resources/jdbc-resource { "command":"Jdbc-resource", @@ -1686,22 +1609,26 @@ http://localhost:4848/management/domain/resources/jdbc-resource } } ---- -2. This step adds a resource as a child of the `jdbc-resource` +2. This step adds a resource as a child of the `jdbc-resource` resource. The `-d` option of the cURL utility sets the required message parameters as follows: ++ * `id` is set to `jdbc/myjdbcresource`. -* `connectionpoolid` is set to `DerbyPool`. + -[source,oac_no_warn] +* `connectionpoolid` is set to `DerbyPool`. ++ +[source] ---- -curl -X POST -H "X-Requested-By: GlassFish REST HTML interface" --d id=jdbc/myjdbcresource -d connectionpoolid=DerbyPool +curl -X POST -H "X-Requested-By: GlassFish REST HTML interface" +-d id=jdbc/myjdbcresource -d connectionpoolid=DerbyPool http://localhost:4848/management/domain/resources/jdbc-resource ---- -3. This step confirms that the object has been added by retrieving data -for the REST resource that represents the object. + -[source,oac_no_warn] + +3. This step confirms that the object has been added by retrieving data +for the REST resource that represents the object. ++ +[source] ---- -curl -X GET -H "Accept: application/json" +curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc%2Fmyjdbcresource { @@ -1737,23 +1664,21 @@ jdbc-resource/jdbc%2Fmyjdbcresource To Update an Object in the Tree +++++++++++++++++++++++++++++++ -1. Ensure that the server is running. + -Operations on REST resources for GlassFish Server data require a running -server. -2. Determine the acceptable message parameters for the `POST` method of -the resource that represents the object. + -For information about how to perform this step, see link:#gjjei[To -Determine the Methods and Method Parameters That an Object in the Tree -Supports]. -3. Use the `POST` method on the REST resource that represents the -object that you are updating. -4. Confirm that the object has been updated. + -For information about how to perform this step, see link:#gjjel[To -Retrieve Data for an Object in the Tree]. +1. Ensure that the server is running. +Operations on REST resources for GlassFish Server data require a running server. -[[GSADG00124]][[gjjhd]] +2. Determine the acceptable message parameters for the `POST` method of +the resource that represents the object. +For information about how to perform this step, +see link:#gjjei[To Determine the Methods and Method Parameters That an Object in the Tree Supports]. + +3. Use the `POST` method on the REST resource that represents the +object that you are updating. +4. Confirm that the object has been updated. +For information about how to perform this step, see link:#gjjel[To Retrieve Data for an Object in the Tree]. +[[GSADG00124]][[gjjhd]] Example 2-32 Updating an Object in the Tree This example uses the cURL utility to update a JDBC resource in the tree @@ -1764,11 +1689,12 @@ for administration is 4848. Line breaks are added to enhance readability. -1. This step determines the acceptable message parameters for the -`POST` method of the resource `jdbc-myjdbcresource`. + -[source,oac_no_warn] +1. This step determines the acceptable message parameters for the +`POST` method of the resource `jdbc-myjdbcresource`. ++ +[source] ---- -curl -X OPTIONS -H "Accept: application/json" +curl -X OPTIONS -H "Accept: application/json" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc-myjdbcresource { @@ -1798,20 +1724,22 @@ jdbc-resource/jdbc-myjdbcresource } } ---- -2. This step updates the REST resource `jdbc-myjdbcresource` to disable +2. This step updates the REST resource `jdbc-myjdbcresource` to disable the JDBC resource that `jdbc-myjdbcresource` represents. The `-d` option -of the cURL utility sets the `enabled` message parameter to `disabled`. + -[source,oac_no_warn] +of the cURL utility sets the `enabled` message parameter to `disabled`. ++ +[source] ---- -curl -X POST -H "X-Requested-By: GlassFish REST HTML interface" +curl -X POST -H "X-Requested-By: GlassFish REST HTML interface" -d "enabled=false" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc%2Fmyjdbcresource ---- -3. This step confirms that the object has been updated by retrieving -data for the REST resource that represents the object. + -[source,oac_no_warn] +3. This step confirms that the object has been updated by retrieving +data for the REST resource that represents the object. ++ +[source] ---- -curl -X GET -H "Accept: application/json" +curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc%2Fmyjdbcresource { @@ -1857,21 +1785,22 @@ jdbc-resource/jdbc%2Fmyjdbcresource To Delete an Object From the Tree +++++++++++++++++++++++++++++++++ -1. Ensure that the server is running. + +1. Ensure that the server is running. ++ Operations on REST resources for GlassFish Server data require a running server. -2. Confirm that the object can be deleted. + +2. Confirm that the object can be deleted. ++ For information about how to perform this step, see link:#gjjei[To Determine the Methods and Method Parameters That an Object in the Tree Supports]. -3. Confirm that the object has been deleted. + +3. Confirm that the object has been deleted. ++ Perform this step on the resource that represents the parent of the object that you have just deleted. For information about how to perform this step, see link:#gjjel[To Retrieve Data for an Object in the Tree]. [[GSADG00125]][[gjjgp]] - - Example 2-33 Deleting an Object From the Tree This example uses the cURL utility to delete a JDBC resource from the @@ -1882,11 +1811,12 @@ for administration is 4848. Line breaks and white space are added to enhance readability. -1. This step confirms that the object can be deleted by retrieving the -REST methods that the resource `jdbc-myjdbcresource` supports. + -[source,oac_no_warn] +1. This step confirms that the object can be deleted by retrieving the +REST methods that the resource `jdbc-myjdbcresource` supports. ++ +[source] ---- -curl -X GET -H "Accept: application/json" +curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc%2Fmyjdbcresource { @@ -1917,18 +1847,20 @@ jdbc-resource/jdbc%2Fmyjdbcresource } } ---- -2. This step deletes the `jdbc/myjdbcresource` resource. + -[source,oac_no_warn] +2. This step deletes the `jdbc/myjdbcresource` resource. ++ +[source] ---- -curl -X DELETE -H "X-Requested-By: GlassFish REST HTML interface" +curl -X DELETE -H "X-Requested-By: GlassFish REST HTML interface" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc%2Fmyjdbcresource ---- -3. This step confirms that the object has been deleted by retrieving -data for the REST resource that represents the parent of the object. + -[source,oac_no_warn] +3. This step confirms that the object has been deleted by retrieving +data for the REST resource that represents the parent of the object. ++ +[source] ---- -curl -X GET -H "Accept: application/json" +curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/resources/jdbc-resource { "command":"Jdbc-resource", @@ -2007,8 +1939,8 @@ Setting up basic authentication over a secure connection to secure GlassFish Server REST interfaces involves the following sequence of tasks: -1. Adding an `admin-realm` user to the `asadmin` user group -2. Enabling Secure Sockets Layer (SSL) +1. Adding an `admin-realm` user to the `asadmin` user group +2. Enabling Secure Sockets Layer (SSL) For information about how to perform these tasks from the command line, see the following documentation: @@ -2036,26 +1968,24 @@ credentials to enable the client to pass the credentials with each request. If you require a REST client not to cache credentials, your client must use session tokens for authentication. -1. Request a session token by using the `GET` method on the resource at -`http://`host`:`port`/management/sessions`. + +1. Request a session token by using the `GET` method on the resource at +`http://`host`:`port`/management/sessions`. GlassFish Server uses basic authentication to authenticate the client, generates a session token, and passes the token to the client. -2. In each subsequent request that requires authentication, use the + +2. In each subsequent request that requires authentication, use the token to authenticate the client. -1. Create a cookie that is named `gfresttoken` the value of which is -the token. -2. Send the cookie with the request. -3. When the token is no longer required, retire the token by using the +.. Create a cookie that is named `gfresttoken` the value of which is the token. +.. Send the cookie with the request. +.. When the token is no longer required, retire the token by using the `DELETE` method on the resource at -`http://`host`:`port`/management/sessions/{`tokenvalue`}`. + - +`http://`host`:`port`/management/sessions/{`tokenvalue`}`. ++ [NOTE] -======================================================================= - +==== If a client does not explicitly retire a token, the token is retired after 30 minutes of inactivity. - -======================================================================= +==== [[gjijz]][[GSADG00711]][[formats-for-resource-representation-of-configuration-objects]] @@ -2100,7 +2030,7 @@ JSON Resource Representation for Configuration Objects The general format for the JSON representation of a resource for a configuration object is as follows: -[source,oac_no_warn] +[source,json] ---- { "command":"resource", @@ -2135,7 +2065,8 @@ attributes:: name-value pair is specified as `"`name`":`value. children:: Zero or more child resources separated by a comma (`,`). Each child - resource is specified as "resource-name":"url". + + resource is specified as "resource-name":"url". ++ resource-name;; The name of the resource as displayed in client applications that access the parent of the resource. @@ -2148,7 +2079,7 @@ JSON Representation of a Command in a Command List The JSON representation of a command in a command list is as follows: -[source,oac_no_warn] +[source,json] ---- { "path":"command-path", @@ -2176,7 +2107,7 @@ JSON Representation of a Method in a Method List The JSON representation of a method in a method list is as follows: -[source,oac_no_warn] +[source,json] ---- { "name":"method-name", @@ -2211,7 +2142,7 @@ JSON Representation of a Message Parameter or a Query Parameter The JSON representation of a message parameter or a query parameter is as follows: -[source,oac_no_warn] +[source,json] ---- "parameter-name":{attribute-list} ---- @@ -2222,19 +2153,22 @@ parameter-name:: The name of the parameter. attribute-list:: A comma-separated list of name-value pairs of attributes for the - parameter. Each pair is in the following format: + -[source,oac_no_warn] + parameter. Each pair is in the following format: ++ +[source,json] ---- "name":"value" ---- :: - Possible attributes are as follows: + + Possible attributes are as follows: ++ `defaultValue`;; The default value of the parameter. `acceptableValues`;; The set or range of acceptable values for the parameter. `type`;; - The data type of the parameter, which is one of the following types: + + The data type of the parameter, which is one of the following types: ++ * `boolean` * `int` * `string` @@ -2256,7 +2190,7 @@ example is `http://localhost:4848/management/domain/nodes/node/sj01`. Line breaks and white space are added to enhance readability. -[source,oac_no_warn] +[source,json] ---- { "command":"Node", @@ -2306,7 +2240,7 @@ XML Resource Representation for Configuration Objects The general format for the XML representation of a resource for a configuration object is as follows: -[source,oac_no_warn] +[source,xml] ---- @@ -2347,8 +2281,9 @@ methods:: Representation of a Resource Method]. attributes:: Zero or more XML elements that represent the attributes of the - resource. Each element specifies a name-value pair as follows: + -[source,oac_no_warn] + resource. Each element specifies a name-value pair as follows: ++ +[source,xml] ---- ---- @@ -2358,8 +2293,9 @@ commands:: element, see link:#gkwaw[XML Representation of a Command]. children:: Zero or more XML elements that represent the children of the resource. - Each element is specified as follows: + -[source,oac_no_warn] + Each element is specified as follows: ++ +[source,xml] ---- ---- @@ -2380,7 +2316,7 @@ XML Representation of a Resource Method The XML representation of a method in a method list is as follows: -[source,oac_no_warn] +[source,xml] ---- @@ -2414,7 +2350,7 @@ XML Representation of a Command The XML representation of a command is as follows: -[source,oac_no_warn] +[source,xml] ---- @@ -2443,7 +2379,7 @@ XML Representation of a Message Parameter or a Query Parameter The XML representation of a message parameter or a query parameter is as follows: -[source,oac_no_warn] +[source,xml] ---- @@ -2460,19 +2396,22 @@ parameter-name:: The name of the parameter. attributes:: One or more XML elements that represent the attributes for the - parameter. Each element specifies a name-value pair as follows: + -[source,oac_no_warn] + parameter. Each element specifies a name-value pair as follows: ++ +[source,xml] ---- ---- :: - Possible attributes are as follows: + + Possible attributes are as follows: ++ `defaultValue`;; The default value of the parameter. `acceptablevalues`;; The set or range of acceptable values for the parameter. `type`;; - The data type of the parameter, which is one of the following types: + + The data type of the parameter, which is one of the following types: ++ * `boolean` * `int` * `string` @@ -2494,7 +2433,7 @@ example is `http://localhost:4848/management/domain/nodes/node/sj01`. Line breaks and white space are added to enhance readability. -[source,oac_no_warn] +[source,xml] ---- @@ -2582,11 +2521,11 @@ Line breaks and white space are added to enhance readability. - - - @@ -2640,7 +2579,7 @@ JSON Resource Representation for Monitoring Objects The general format for the JSON representation of a resource for a monitoring object is as follows: -[source,oac_no_warn] +[source,json] ---- { "message":"", @@ -2668,7 +2607,8 @@ statistics-list:: in a Statistics List]. children:: Zero or more child resources separated by a comma (`,`). Each child - resource is specified as "resource-name":"url". + + resource is specified as "resource-name":"url". ++ resource-name;; The name of the resource as displayed in client applications that access the parent of the resource. @@ -2682,7 +2622,7 @@ JSON Representation of a Statistic in a Statistics List The JSON representation of a counter statistic in a statistics list is as follows: -[source,oac_no_warn] +[source,json] ---- "statistic":{ "count":count, @@ -2697,11 +2637,11 @@ as follows: The JSON representation of a range statistic in a statistics list is as follows: -[source,oac_no_warn] +[source,json] ---- "statistic":{ - "highwatermark":highest-value, - "lowwatermark":lowest-value, + "highwatermark":highest-value, + "lowwatermark":lowest-value, "current":current-value "lastsampletime":last-sample-time, "description":"description", @@ -2732,7 +2672,8 @@ description:: A textual description of what the statistic represents. unit:: The unit of measurement of the statistic, which is one of the - following units of measurement: + + following units of measurement: ++ `count`;; The cumulative value of an attribute that increases with time. `range`;; @@ -2748,7 +2689,8 @@ unit:: example, `CONNECTED`, `CLOSED`, or `DISCONNECTED`. `time`;; Values of an attribute that provide the following timing - measurements for an operation: + + measurements for an operation: ++ * The number of times the operation was performed. * The maximum amount of time to perform the operation once. * The minimum amount of time to perform the operation once. @@ -2774,7 +2716,7 @@ example is Line breaks and white space are added to enhance readability. -[source,oac_no_warn] +[source,json] ---- { "message":"", @@ -2785,7 +2727,7 @@ Line breaks and white space are added to enhance readability. "loadedclass-count":{ "count":8521, "lastsampletime":1300726961018, - "description":"Number of classes currently loaded in the Java virtual + "description":"Number of classes currently loaded in the Java virtual machine", "unit":"count", "name":"LoadedClassCount", @@ -2794,7 +2736,7 @@ Line breaks and white space are added to enhance readability. "totalloadedclass-count":{ "count":8682, "lastsampletime":1300726961018, - "description":"Total number of classes that have been loaded since the + "description":"Total number of classes that have been loaded since the Java virtual machine has started execution", "unit":"count", "name":"TotalLoadedClassCount", @@ -2803,7 +2745,7 @@ Line breaks and white space are added to enhance readability. "unloadedclass-count":{ "count":161, "lastsampletime":1300726961018, - "description":"Total number of classes unloaded since the Java virtual + "description":"Total number of classes unloaded since the Java virtual machine has started execution", "unit":"count", "name":"UnLoadedClassCount", @@ -2822,7 +2764,7 @@ XML Resource Representation for Monitoring Objects The general format for the XML representation of a resource for a monitoring object is as follows: -[source,oac_no_warn] +[source,xml] ---- @@ -2854,8 +2796,9 @@ statistics:: link:#gkwjv[XML Representation of a Statistic]. children:: Zero or more XML elements that represent the children of the resource. - Each element is specified as follows: + -[source,oac_no_warn] + Each element is specified as follows: ++ +[source,xml] ---- ---- @@ -2874,7 +2817,7 @@ XML Representation of a Statistic The XML representation of a counter statistic is as follows: -[source,oac_no_warn] +[source,xml] ---- @@ -2896,7 +2839,7 @@ The XML representation of a counter statistic is as follows: The XML representation of a range statistic is as follows: -[source,oac_no_warn] +[source,xml] ---- @@ -2928,7 +2871,8 @@ statistic:: The name of the statistic. unit:: The unit of measurement of the statistic, which is one of the - following units of measurement: + + following units of measurement: ++ `count`;; The cumulative value of an attribute that increases with time. `range`;; @@ -2944,7 +2888,8 @@ unit:: example, `CONNECTED`, `CLOSED`, or `DISCONNECTED`. `time`;; Values of an attribute that provide the following timing - measurements for an operation: + + measurements for an operation: ++ * The number of times the operation was performed. * The maximum amount of time to perform the operation once. * The minimum amount of time to perform the operation once. @@ -2985,7 +2930,7 @@ example is Line breaks and white space are added to enhance readability. -[source,oac_no_warn] +[source,xml] ---- @@ -3001,7 +2946,7 @@ Line breaks and white space are added to enhance readability. 161 - @@ -3018,7 +2963,7 @@ Line breaks and white space are added to enhance readability. number>8682 - @@ -3034,7 +2979,7 @@ Line breaks and white space are added to enhance readability. 8521 - @@ -3099,7 +3044,7 @@ JSON Resource Representation for Log File Details The general format for the JSON representation of a resource for log file details is as follows: -[source,oac_no_warn] +[source,json] ---- { "records": [ @@ -3119,7 +3064,7 @@ JSON Representation of a Log Record in a Record List The JSON representation of a log record in a record list is as follows: -[source,oac_no_warn] +[source,json] ---- { "recordNumber":record-number, @@ -3177,7 +3122,7 @@ example is `http://localhost:4848/management/domain/view-log/details`. Line breaks and white space are added to enhance readability. -[source,oac_no_warn] +[source,json] ---- { "records": [ @@ -3223,7 +3168,7 @@ XML Resource Representation for Log File Details The general format for the XML representation of a resource for log file details is as follows: -[source,oac_no_warn] +[source,xml] ---- records @@ -3241,10 +3186,10 @@ XML Representation of a Log Record The XML representation of a log record is as follows: -[source,oac_no_warn] +[source,xml] ---- - ---- @@ -3291,20 +3236,20 @@ example is `http://localhost:4848/management/domain/view-log/details`. Line breaks and white space are added to enhance readability. -[source,oac_no_warn] +[source,xml] ---- - - - ---- diff --git a/docs/administration-guide/src/main/jbake/content/http_https.adoc b/docs/administration-guide/src/main/jbake/content/http_https.adoc index 6d3392a518f5..2cd4baf4c1a2 100644 --- a/docs/administration-guide/src/main/jbake/content/http_https.adoc +++ b/docs/administration-guide/src/main/jbake/content/http_https.adoc @@ -4,6 +4,7 @@ title=Administering Internet Connectivity next=concurrent.html prev=connectors.html ~~~~~~ + Administering Internet Connectivity =================================== @@ -101,12 +102,10 @@ registered with the DNS server for your network. [NOTE] -======================================================================= - +==== Do not confuse an Internet domain with the administrative domain of GlassFish Server. - -======================================================================= +==== For example, assume that you want to host the following domains on your @@ -115,7 +114,7 @@ that these domains are respectively associated with web modules `web1`, `web2`, and `web3`. This means that the following URLs are handled by your physical server: -[source,oac_no_warn] +[source] ---- http://www.aaa.com:8080/web1 http://www.bbb.com:8080/web2 @@ -140,10 +139,8 @@ By default, when GlassFish Server starts, the following HTTP listeners are started automatically: * HTTP listeners associated with the virtual server named `server`: - ** The listener named `http-listener-1` does not have security enabled. - -** The listener named `http-listener-2` has security enabled +** The listener named `http-listener-2` has security enabled. * An HTTP listener named `admin-listener`, associated with the virtual server named `__asadmin`. For this listener, security is not enabled. @@ -164,18 +161,12 @@ the Administration Console, specify the port number in the URL of the browser. When running an `asadmin` subcommand remotely, specify the port number by using the `--port` option. -|HTTP |8080 |The web server listens for HTTP requests on a port. To -access deployed web applications and services, clients connect to this -port. +|HTTP |8080 |The web server listens for HTTP requests on a port. +To access deployed web applications and services, clients connect to this port. |HTTPS |8181 |Web applications configured for secure communications listen on a separate port. -| | | - -| | | - -| | | |======================================================================= @@ -197,30 +188,26 @@ with the full range of listener options. A network listener is created behind the scenes. For the shortcut version of this process , see link:#gjimx[To Create an HTTP Network Listener]. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create an HTTP or HTTPS protocol by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create an HTTP or HTTPS protocol by using the link:../reference-manual/create-protocol.html#GSRFM00051[`create-protocol`] subcommand with the -`--securityenabled` option. + -To use the built-in `http-listener-1` HTTP protocol, or -`http-listener-2` HTTPS protocol, skip this step. -3. Create an HTTP configuration by using the -link:../reference-manual/create-http.html#GSRFM00025[`create-http`] subcommand. + +`--securityenabled` option. +To use the built-in `http-listener-1` HTTP protocol, +or `http-listener-2` HTTPS protocol, skip this step. +3. Create an HTTP configuration by using the +link:../reference-manual/create-http.html#GSRFM00025[`create-http`] subcommand. To use a built-in protocol, skip this step. -4. Create a transport by using the link:../reference-manual/create-transport.html#GSRFM00061[`create-transport`] -subcommand. + -To use the built-in `tcp` transport, skip this step. -5. Create a thread pool by using the -link:../reference-manual/create-threadpool.html#GSRFM00060[`create-threadpool`] subcommand. + +4. Create a transport by using the link:../reference-manual/create-transport.html#GSRFM00061[`create-transport`] +subcommand. To use the built-in `tcp` transport, skip this step. +5. Create a thread pool by using the +link:../reference-manual/create-threadpool.html#GSRFM00060[`create-threadpool`] subcommand. To avoid using a thread pool, or to use the built-in `http-thread-pool` -thread pool, skip this step. + -For additional thread pool information, see -link:threadpools.html#abluc[Administering Thread Pools]. -6. Create an HTTP listener by using the -link:../reference-manual/create-network-listener.html#GSRFM00046[`create-network-listener`] subcommand. + +thread pool, skip this step. +For additional thread pool information, see link:threadpools.html#abluc[Administering Thread Pools]. +6. Create an HTTP listener by using the +link:../reference-manual/create-network-listener.html#GSRFM00046[`create-network-listener`] subcommand. Specify a protocol and transport, optionally a thread pool. -7. To apply your changes, restart GlassFish Server. + -See link:domains.html#ginqj[To Restart a Domain]. +7. To apply your changes, restart GlassFish Server. See link:domains.html#ginqj[To Restart a Domain]. [[GSADG991]] @@ -254,20 +241,18 @@ To Create a Protocol Use the `create-protocol` subcommand in remote mode to create a protocol. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create a protocol by using the link:../reference-manual/create-protocol.html#GSRFM00051[`create-protocol`] + +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create a protocol by using the link:../reference-manual/create-protocol.html#GSRFM00051[`create-protocol`] ++ Information about options and properties for the subcommand are included in this help page. [[GSADG00245]][[gjhos]] - - Example 13-1 Creating an HTTP Protocol This example creates a protocol named `http-1` with security enabled. -[source,oac_no_warn] +[source] ---- asadmin> create-protocol --securityenabled=true http-1 Command create-protocol executed successfully. @@ -288,19 +273,16 @@ To List Protocols Use the `list-protocols` subcommand in remote mode to list the existing HTTP protocols. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the existing protocols by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the existing protocols by using the link:../reference-manual/list-protocols.html#GSRFM00195[`list-protocols`] subcommand. [[GSADG00246]][[gjhqg]] - - Example 13-2 Listing the Protocols This example lists the existing protocols. -[source,oac_no_warn] +[source] ---- asadmin> list-protocols admin-listener @@ -325,19 +307,16 @@ To Delete a Protocol Use the `delete-protocol` subcommand in remote mode to remove a protocol. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Delete a protocol by using the link:../reference-manual/delete-protocol.html#GSRFM00103[`delete-protocol`] +1. Ensure that the server is running. Remote subcommands require a running server. +2. Delete a protocol by using the link:../reference-manual/delete-protocol.html#GSRFM00103[`delete-protocol`] subcommand [[GSADG00247]][[gjhop]] - - Example 13-3 Deleting a Protocol This example deletes the protocol named `http-1`. -[source,oac_no_warn] +[source] ---- asadmin> delete-protocol http-1 Command delete-protocol executed successfully. @@ -374,22 +353,19 @@ Use the `create-http` subcommand in remote mode to create a set of HTTP parameters for a protocol. This set of parameters configures one or more network listeners, -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create an HTTP configuration by using the -link:../reference-manual/create-http.html#GSRFM00025[`create-http`] subcommand. + +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create an HTTP configuration by using the +link:../reference-manual/create-http.html#GSRFM00025[`create-http`] subcommand. Information about options and properties for the subcommand are included in this help page. [[GSADG00248]][[gjhnz]] - - Example 13-4 Creating an HTTP Configuration This example creates an HTTP parameter set for the protocol named `http-1`. -[source,oac_no_warn] +[source] ---- asadmin> create-http --timeout-seconds 60 --default-virtual-server server http-1 Command create-http executed successfully. @@ -410,20 +386,16 @@ To Delete an HTTP Configuration Use the `delete-http` subcommand in remote mode to remove HTTP parameters from a protocol. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Delete the HTTP parameters from a protocol by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Delete the HTTP parameters from a protocol by using the link:../reference-manual/delete-http.html#GSRFM00077[`delete-http`] subcommand. [[GSADG00249]][[gjhov]] - - Example 13-5 Deleting an HTTP Configuration -This example deletes the HTTP parameter set from a protocol named -`http-1`. +This example deletes the HTTP parameter set from a protocol named `http-1`. -[source,oac_no_warn] +[source] ---- asadmin> delete-http http-1 Command delete-http executed successfully. @@ -460,22 +432,18 @@ To Create a Transport Use the `create-transport` subcommand in remote mode to create a transport for a network listener, -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create a transport by using the link:../reference-manual/create-transport.html#GSRFM00061[`create-transport`] -subcommand. + -Information about options and properties for the subcommand are included -in this help page. +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create a transport by using the link:../reference-manual/create-transport.html#GSRFM00061[`create-transport`] +subcommand. +Information about options and properties for the subcommand are included in this help page. [[GSADG00250]][[gjhpx]] - - Example 13-6 Creating a Transport This example creates a transport named `http1-trans` that uses a non-default number of acceptor threads. -[source,oac_no_warn] +[source] ---- asadmin> create-transport --acceptorthreads 100 http1-trans Command create-transport executed successfully. @@ -496,19 +464,16 @@ To List Transports Use the `list-transports` subcommand in remote mode to list the existing HTTP transports. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the existing transports by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the existing transports by using the link:../reference-manual/list-transports.html#GSRFM00206[`list-transports`] subcommand. [[GSADG00251]][[gjhqj]] - - Example 13-7 Listing HTTP Transports This example lists the existing transports. -[source,oac_no_warn] +[source] ---- asadmin> list-transports http1-trans @@ -531,22 +496,19 @@ To Delete a Transport Use the `delete-transport` subcommand in remote mode to remove a transport. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Delete a transport by using the link:../reference-manual/delete-transport.html#GSRFM00112[`delete-transport`] +1. Ensure that the server is running. Remote subcommands require a running server. +2. Delete a transport by using the link:../reference-manual/delete-transport.html#GSRFM00112[`delete-transport`] subcommand. [[GSADG00252]][[gjhoh]] - - Example 13-8 Deleting a Transport This example deletes he transport named `http1-trans`. -[source,oac_no_warn] +[source] ---- asadmin> delete-transport http1-trans -Command delete-transport executed successfully. +Command delete-transport executed successfully. ---- [[GSADG999]] @@ -589,43 +551,39 @@ of options. If you want to specify the full range of listener options, follow the instructions in link:#ggnfh[To Create an Internet Connection]. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create an HTTP network listener by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create an HTTP network listener by using the link:../reference-manual/create-network-listener.html#GSRFM00046[`create-network-listener`] subcommand or the link:../reference-manual/create-http-listener.html#GSRFM00030[`create-http-listener`] subcommand. -3. If needed, restart the server. + +3. If needed, restart the server. ++ If you edit the special HTTP network listener named `admin-listener`, you must restart the server for changes to take effect. See link:domains.html#ginqj[To Restart a Domain]. [[GSADG00253]][[ggpjk]] - - Example 13-9 Creating an HTTP Listener This example creates an HTTP listener named `sampleListener` that uses a non-default number of acceptor threads. Security is not enabled at runtime. -[source,oac_no_warn] +[source] ---- -asadmin> create-http-listener --listeneraddress 0.0.0.0 ---listenerport 7272 --defaultvs server --servername host1.sun.com ---acceptorthreads 100 --securityenabled=false +asadmin> create-http-listener --listeneraddress 0.0.0.0 +--listenerport 7272 --defaultvs server --servername host1.sun.com +--acceptorthreads 100 --securityenabled=false --enabled=false sampleListener Command create-http-listener executed successfully. ---- [[GSADG00254]][[gjimj]] - - Example 13-10 Creating a Network Listener This example a network listener named `sampleListener` that is not enabled at runtime: -[source,oac_no_warn] +[source] ---- asadmin> create-network-listener --listenerport 7272 protocol http-1 --enabled=false sampleListener @@ -648,21 +606,18 @@ To List HTTP Network Listeners Use the `list-http-listeners` subcommand or the `list-network-listeners` subcommand in remote mode to list the existing HTTP listeners. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List HTTP listeners by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List HTTP listeners by using the link:../reference-manual/list-http-listeners.html#GSRFM00168[`list-http-listeners`] or link:../reference-manual/list-network-listeners.html#GSRFM00186[`list-network-listeners`] subcommand. [[GSADG00255]][[ggpgw]] - - Example 13-11 Listing HTTP Listeners This example lists the HTTP listeners. The same output is given if you use the `list-network-listeners` subcommand. -[source,oac_no_warn] +[source] ---- asadmin> list-http-listeners admin-listener @@ -684,21 +639,20 @@ typing `asadmin help list-http-listeners` or To Update an HTTP Network Listener ++++++++++++++++++++++++++++++++++ -1. List HTTP listeners by using the +1. List HTTP listeners by using the link:../reference-manual/list-http-listeners.html#GSRFM00168[`list-http-listeners`] or link:../reference-manual/list-network-listeners.html#GSRFM00186[`list-network-listeners`] subcommand. -2. Modify the values for the specified listener by using the -link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. + +2. Modify the values for the specified listener by using the +link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. ++ The listener is identified by its dotted name. [[GSADG00256]][[giwiw]] - - Example 13-12 Updating an HTTP Network Listener This example changes `security-enabled` to `false` on `http-listener-2`. -[source,oac_no_warn] +[source] ---- asadmin> set server.network-config.protocols.protocol.http-listener-2.security-enabled=false Command set executed successfully. @@ -714,24 +668,22 @@ Use the `delete-http-listener` subcommand or the existing HTTP listener. This disables secure communications for the listener. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List HTTP listeners by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List HTTP listeners by using the link:../reference-manual/list-http-listeners.html#GSRFM00168[`list-http-listeners`] subcommand. -3. Delete an HTTP listener by using the +3. Delete an HTTP listener by using the link:../reference-manual/delete-http-listener.html#GSRFM00082[`delete-http-listener`] or link:../reference-manual/delete-network-listener.html#GSRFM00098[`delete-network-listener`] subcommand. -4. To apply your changes, restart GlassFish Server. + +4. To apply your changes, restart GlassFish Server. ++ See link:domains.html#ginqj[To Restart a Domain]. [[GSADG00257]][[ggpjr]] - - Example 13-13 Deleting an HTTP Listener This example deletes the HTTP listener named `sampleListener`: -[source,oac_no_warn] +[source] ---- asadmin> delete-http-listener sampleListener Command delete-http-listener executed successfully. @@ -754,21 +706,19 @@ Use the `create-ssl` subcommand in remote mode to create and configure an SSL element in the specified listener. This enables secure communication for the listener. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Configure an HTTP listener by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Configure an HTTP listener by using the link:../reference-manual/create-ssl.html#GSRFM00058[`create-ssl`] subcommand. -3. To apply your changes, restart GlassFish Server. + +3. To apply your changes, restart GlassFish Server. ++ See link:domains.html#ginqj[To Restart a Domain]. [[GSADG00258]][[ggphv]] - - Example 13-14 Configuring an HTTP Listener for SSL This example enables the HTTP listener named `http-listener-1` for SSL: -[source,oac_no_warn] +[source] ---- asadmin> create-ssl --type http-listener --certname sampleCert http-listener-1 Command create-ssl executed successfully. @@ -792,7 +742,7 @@ connection, but does not refuse a connection if the client does not provide one. To enable this feature, set the `client-auth` property of the SSL protocol to the value `want`. For example: -[source,oac_no_warn] +[source] ---- asadmin> set configs.config.config-name.network-config.protocols.\ protocol.listener-name.ssl.client-auth=want @@ -809,7 +759,7 @@ feature, set the `classname` property of the SSL protocol to the name of a class that implements the `com.sun.grizzly.util.net.SSLImplementation` interface. For example: -[source,oac_no_warn] +[source] ---- asadmin> set configs.config.config-name.network-config.protocols.\ protocol.listener-name.ssl.classname=SSLImplementation-class-name @@ -827,21 +777,19 @@ Use the `delete-ssl` subcommand in remote mode to delete the SSL element in the specified listener. This disables secure communications for the listener. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Delete SSL from an HTTP listener by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Delete SSL from an HTTP listener by using the link:../reference-manual/delete-ssl.html#GSRFM00109[`delete-ssl`] subcommand. -3. To apply your changes, restart GlassFish Server. + +3. To apply your changes, restart GlassFish Server. ++ See link:domains.html#ginqj[To Restart a Domain]. [[GSADG00259]][[ggpln]] - - Example 13-15 Deleting SSL From an HTTP Listener This example disables SSL for the HTTP listener named `http-listener-1`: -[source,oac_no_warn] +[source] ---- asadmin> delete-ssl --type http-listener http-listener-1 Command delete-http-listener executed successfully. @@ -859,11 +807,12 @@ typing `asadmin help delete-ssl` at the command line. To Assign a Default Virtual Server to an HTTP Listener ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -1. In the Administration Console, open the HTTP Service component under +1. In the Administration Console, open the HTTP Service component under the relevant configuration. -2. Open the HTTP Listeners component under the HTTP Service component. -3. Select or create a new HTTP listener. -4. Select from the Default Virtual Server drop-down list. + +2. Open the HTTP Listeners component under the HTTP Service component. +3. Select or create a new HTTP listener. +4. Select from the Default Virtual Server drop-down list. ++ For more information, see link:#beaga[To Assign a Default Web Module to a Virtual Server]. @@ -903,7 +852,7 @@ Source Edition Application Deployment Guide]. You can define virtual server properties using the `asadmin set` command. For example: -[source,oac_no_warn] +[source] ---- asadmin> set server-config.http-service.virtual-server.MyVS.property.sso-enabled="true" ---- @@ -931,7 +880,8 @@ By default, when GlassFish Server starts, the following virtual servers are started automatically: * A virtual server named `server`, which hosts all user-defined web -modules. + +modules. ++ For development, testing, and deployment of web services in a non-production environment, `server` is often the only virtual server required. @@ -956,24 +906,23 @@ virtual server cannot specify an HTTP listener that is already being used by another virtual server, create at least one HTTP listener before creating a new virtual server. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create a virtual server by using the -link:../reference-manual/create-virtual-server.html#GSRFM00062[`create-virtual-server`] subcommand. + +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create a virtual server by using the +link:../reference-manual/create-virtual-server.html#GSRFM00062[`create-virtual-server`] subcommand. ++ Information about properties for this subcommand is included in this help page. -3. To apply your changes, restart GlassFish Server. + +3. To apply your changes, restart GlassFish Server. ++ See link:domains.html#ginqj[To Restart a Domain]. [[GSADG00260]][[ggpha]] - - Example 13-16 Creating a Virtual Server This example creates a virtual server named `sampleServer` on `localhost`. -[source,oac_no_warn] +[source] ---- asadmin> create-virtual-server sampleServer Command create-virtual-server executed successfully. @@ -994,19 +943,16 @@ To List Virtual Servers Use the `list-virtual-servers` subcommand in remote mode to list the existing virtual servers. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List virtual servers by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List virtual servers by using the link:../reference-manual/list-virtual-servers.html#GSRFM00207[`list-virtual-servers`] subcommand. [[GSADG00261]][[ggpgr]] - - Example 13-17 Listing Virtual Servers This example lists the virtual servers for `localhost`. -[source,oac_no_warn] +[source] ---- asadmin> list-virtual-servers sampleListener @@ -1028,10 +974,11 @@ typing `asadmin help list-virutal-servers` at the command line. To Update a Virtual Server ^^^^^^^^^^^^^^^^^^^^^^^^^^ -1. List virtual servers by using the +1. List virtual servers by using the link:../reference-manual/list-virtual-servers.html#GSRFM00207[`list-virtual-servers`] subcommand. -2. Modify the values for the specified virtual server by using the -link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. + +2. Modify the values for the specified virtual server by using the +link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. ++ The virtual server is identified by its dotted name. [[ggnen]][[GSADG00475]][[to-delete-a-virtual-server]] @@ -1042,25 +989,23 @@ To Delete a Virtual Server Use the `delete-virtual-server` subcommand in remote mode to delete an existing virtual server. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List virtual servers by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List virtual servers by using the link:../reference-manual/list-virtual-servers.html#GSRFM00207[`list-virtual-servers`] subcommand. -3. If necessary, notify users that the virtual server is being deleted. -4. Delete a virtual server by using the +3. If necessary, notify users that the virtual server is being deleted. +4. Delete a virtual server by using the link:../reference-manual/delete-virtual-server.html#GSRFM00113[`delete-virtual-server`] subcommand. -5. To apply your changes, restart GlassFish Server. + +5. To apply your changes, restart GlassFish Server. ++ See link:domains.html#ginqj[To Restart a Domain]. [[GSADG00262]][[ggpmd]] - - Example 13-18 Deleting a Virtual Server This example deletes the virtual server named `sampleServer` from `localhost`. -[source,oac_no_warn] +[source] ---- asadmin> delete-virtual-server sampleServer Command delete-virtual-server executed successfully. @@ -1083,7 +1028,7 @@ to each new virtual server. To access the default web module for a virtual server, point the browser to the URL for the virtual server, but do not supply a context root. For example: -[source,oac_no_warn] +[source] ---- http://myvserver:3184/ ---- @@ -1096,7 +1041,7 @@ but specify the target file. For example: -[source,oac_no_warn] +[source] ---- http://myvserver:3184/hellothere.jsp ---- @@ -1116,13 +1061,14 @@ The application or module must already be deployed. For more information, see the link:../application-deployment-guide/toc.html#GSDPG[GlassFish Server Open Source Edition Application Deployment Guide]. -1. In the Administration Console, open the HTTP Service component under +1. In the Administration Console, open the HTTP Service component under the relevant configuration. -2. Open the Virtual Servers component under the HTTP Service component. -3. Select the virtual server to which you want to assign a default web +2. Open the Virtual Servers component under the HTTP Service component. +3. Select the virtual server to which you want to assign a default web module. -4. Select the application or web module from the Default Web Module -drop-down list. + +4. Select the application or web module from the Default Web Module +drop-down list. ++ For more information, see link:#beaga[To Assign a Default Web Module to a Virtual Server]. @@ -1149,7 +1095,8 @@ The values supported for these attributes are as follows: the `HttpOnly` attribute is not included. `sso-cookie-secure`:: A string value that specifies whether the `Secure` attribute is - included in `JSESSIONIDSSO` cookies. Allowed values are as follows: + + included in `JSESSIONIDSSO` cookies. Allowed values are as follows: ++ * `true` — The `Secure` attribute is included. * `false` — The `Secure` attribute is not included. * `dynamic` — The `Secure` attribute setting is inherited from the diff --git a/docs/administration-guide/src/main/jbake/content/javamail.adoc b/docs/administration-guide/src/main/jbake/content/javamail.adoc index b1f823af1d8e..5bd9a9bda1c6 100644 --- a/docs/administration-guide/src/main/jbake/content/javamail.adoc +++ b/docs/administration-guide/src/main/jbake/content/javamail.adoc @@ -4,6 +4,7 @@ title=Administering the JavaMail Service next=jms.html prev=orb.html ~~~~~~ + Administering the JavaMail Service ================================== @@ -100,25 +101,24 @@ JavaMail session resource. The JNDI name for a JavaMail session resource customarily includes the mail/ naming subcontext, For example: `mail/MyMailSession.` -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create a JavaMail resource by using the -link:../reference-manual/create-javamail-resource.html#GSRFM00035[`create-javamail-resource`] subcommand. + +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create a JavaMail resource by using the +link:../reference-manual/create-javamail-resource.html#GSRFM00035[`create-javamail-resource`] subcommand. ++ Information about the properties for the subcommand is included in this help page. -3. To apply your changes, restart GlassFish Server. + +3. To apply your changes, restart GlassFish Server. ++ See link:domains.html#ginqj[To Restart a Domain]. [[GSADG00267]][[gipfs]] - - Example 16-1 Creating a JavaMail Resource This example creates a JavaMail resource named `mail/MyMailSession`. The escape character (\) is used in the `--fromaddress` option to distinguish the dot (.) and at sign (@). -[source,oac_no_warn] +[source] ---- asadmin> create-javamail-resource --mailhost localhost --mailuser sample --fromaddress sample\@sun\.com mail/MyMailSession @@ -140,19 +140,16 @@ To List JavaMail Resources Use the `list-javamail-resources` subcommand in remote mode to list the existing JavaMail session resources. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the JavaMail resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the JavaMail resources by using the link:../reference-manual/list-javamail-resources.html#GSRFM00172[`list-javamail-resources`] subcommand. [[GSADG00268]][[gipfe]] - - Example 16-2 Listing JavaMail Resources This example lists the JavaMail resources on `localhost`. -[source,oac_no_warn] +[source] ---- asadmin> list-javamail-resources mail/MyMailSession @@ -171,20 +168,19 @@ typing `asadmin help list-javamail-resources` at the command line. To Update a JavaMail Resource ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -1. List the JavaMail resources by using the +1. List the JavaMail resources by using the link:../reference-manual/list-javamail-resources.html#GSRFM00172[`list-javamail-resources`] subcommand. -2. Modify the values for the specified JavaMail source by using the -link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. + +2. Modify the values for the specified JavaMail source by using the +link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. ++ The resource is identified by its dotted name. [[GSADG00269]][[giwjb]] - - Example 16-3 Updating a JavaMail Resource This example changes `joeserver` to `joe`. -[source,oac_no_warn] +[source] ---- asadmin> set server.resources.mail-resource.mail/ MyMailSession.user=joeserver.resources.mail-resource.mail/ @@ -207,24 +203,22 @@ Before You Begin References to the specified resource must be removed before running the `delete-javamail-resource` subcommands. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the JavaMail resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the JavaMail resources by using the link:../reference-manual/list-javamail-resources.html#GSRFM00172[`list-javamail-resources`] subcommands. -3. Delete a JavaMail resource by using the +3. Delete a JavaMail resource by using the link:../reference-manual/delete-javamail-resource.html#GSRFM00087[`delete-javamail-resource`] subcommands. -4. To apply your changes, restart GlassFish Server. + +4. To apply your changes, restart GlassFish Server. ++ See link:domains.html#ginqj[To Restart a Domain]. [[GSADG00270]][[gipcd]] - - Example 16-4 Deleting a JavaMail Resource This example deletes the JavaMail session resource named `mail/MyMailSession`. -[source,oac_no_warn] +[source] ---- asadmin> delete-javamail-resource mail/MyMailSession Command delete-javamail-resource executed successfully. diff --git a/docs/administration-guide/src/main/jbake/content/jdbc.adoc b/docs/administration-guide/src/main/jbake/content/jdbc.adoc index f1d9887a0650..4a66fbee1b62 100644 --- a/docs/administration-guide/src/main/jbake/content/jdbc.adoc +++ b/docs/administration-guide/src/main/jbake/content/jdbc.adoc @@ -4,6 +4,7 @@ title=Administering Database Connectivity next=connectors.html prev=part-res-and-svcs-admin.html ~~~~~~ + Administering Database Connectivity =================================== @@ -63,21 +64,27 @@ link:#ghatb[Integrating the JDBC Driver]. At runtime, the following sequence occurs when an application connects to a database: -1. The application gets the JDBC resource associated with the database -by making a call through the JNDI API. + +1. The application gets the JDBC resource associated with the database +by making a call through the JNDI API. ++ Using the JNDI name of the resource, the naming and directory service locates the JDBC resource. Each JDBC resource specifies a connection pool. -2. Using the JDBC resource, the application gets a database connection. + + +2. Using the JDBC resource, the application gets a database connection. ++ GlassFish Server retrieves a physical connection from the connection pool that corresponds to the database. The pool defines connection attributes such as the database name (URL), user name, and password. -3. After the database connection is established, the application can -read, modify, and add data to the database. + + +3. After the database connection is established, the application can +read, modify, and add data to the database. ++ The application accesses the database by making calls to the JDBC API. The JDBC driver translates the application's JDBC calls into the protocol of the database server. -4. When the application is finished accessing the database, the + +4. When the application is finished accessing the database, the application closes the connection and returns the connection to the connection pool. @@ -102,17 +109,23 @@ The following topics are addressed here: To Install the Database and Database Driver ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -1. Install a supported database product. + +1. Install a supported database product. ++ To see the current list of database products supported by GlassFish -Server, refer to the link:../release-notes/toc.html#GSRLN[GlassFish Server Open Source Edition -Release Notes]. -2. Install a supported JDBC driver for the database product. + +Server, refer to the link:../release-notes/toc.html#GSRLN[GlassFish Server Open Source Edition Release Notes]. + +2. Install a supported JDBC driver for the database product. ++ For a list of drivers supported by GlassFish Server, see link:#beamw[Configuration Specifics for JDBC Drivers]. -3. Make the JDBC driver JAR file accessible to the domain -administration server (DAS). + + +3. Make the JDBC driver JAR file accessible to the domain +administration server (DAS). ++ See link:#ghatb[Integrating the JDBC Driver]. -4. Create the database. + + +4. Create the database. ++ The application provider usually delivers scripts for creating and populating the database. @@ -150,17 +163,13 @@ with its standard output and standard error information. * The database files contain your schema (for example, database tables). [[GSADG00212]][[ggooc]] - - Example 11-1 Starting a Database This example starts the Apache Derby database on the host host1 and port -5001. - -[source,oac_no_warn] +5001. [source] ---- asadmin> start-database --dbhost host1 --dbport 5001 --terse=true -Starting database in the background. +Starting database in the background. Log redirected to /opt/SUNWappserver/databases/javadb.log. Command start-database executed successfully. ---- @@ -181,23 +190,21 @@ Use the local `stop-database` subcommand to stop the Apache Derby database on a specified port. A single host can have multiple database server processes running on different ports. -1. If necessary, notify users that the database is being stopped. -2. Stop the database by using the link:../reference-manual/stop-database.html#GSRFM00239[`stop-database`] +1. If necessary, notify users that the database is being stopped. +2. Stop the database by using the link:../reference-manual/stop-database.html#GSRFM00239[`stop-database`] subcommand. [[GSADG00213]][[ggorc]] - - Example 11-2 Stopping a Database This example stops the Apache Derby database on port 5001 of `localhost`. -[source,oac_no_warn] +[source] ---- asadmin> stop-database --dbhost=localhost --dbport=5001 onnection obtained for host: localhost, port number 5001. -Apache Derby Network Server - 10.2.2.1 - (538595) shutdown +Apache Derby Network Server - 10.2.2.1 - (538595) shutdown at 2008-10-17 23:34:2 7.218 GMT Command stop-database executed successfully. ---- @@ -252,9 +259,9 @@ as-install`/javadb/bin` directory: To Configure Your Environment to Run the Apache Derby Database Utility Scripts ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -1. Ensure that the `JAVA_HOME` environment variable specifies the +1. Ensure that the `JAVA_HOME` environment variable specifies the directory where the JDK is installed. -2. Set the `JAVADB_HOME` environment variable to point to the +2. Set the `JAVADB_HOME` environment variable to point to the as-install`/javadb` directory. [[GSADG953]] @@ -360,27 +367,25 @@ Before creating the connection pool, you must first install and integrate the database and its associated JDBC driver. For instructions, see link:#ggkon[Setting Up the Database]. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create the JDBC connection pool by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create the JDBC connection pool by using the link:../reference-manual/create-jdbc-connection-pool.html#GSRFM00036[`create-jdbc-connection-pool`] subcommand. -3. If needed, restart the server. + +3. If needed, restart the server. ++ Some parameters require server restart. See link:overview.html#ghciy[Configuration Changes That Require Restart]. [[GSADG00214]][[ggrgh]] - - Example 11-3 Creating a JDBC Connection Pool This example creates a JDBC connection pool named `sample_derby_pool` on `localhost`. -[source,oac_no_warn] +[source] ---- -asadmin> create-jdbc-connection-pool ---datasourceclassname org.apache.derby.jdbc.ClientDataSource ---restype javax.sql.XADataSource +asadmin> create-jdbc-connection-pool +--datasourceclassname org.apache.derby.jdbc.ClientDataSource +--restype javax.sql.XADataSource --property portNumber=1527:password=APP:user=APP:serverName= localhost:databaseName=sun-appserv-samples:connectionAttribut es=\;create\\=true sample_derby_pool @@ -402,19 +407,16 @@ To List JDBC Connection Pools Use the `list-jdbc-connection-pools` subcommand in remote mode to list all existing JDBC connection pools. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the JDBC connection pools by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the JDBC connection pools by using the link:../reference-manual/list-jdbc-connection-pools.html#GSRFM00173[`list-jdbc-connection-pools`] subcommand. [[GSADG00215]][[ggpcf]] - - Example 11-4 Listing JDBC Connection Pools This example lists the JDBC connection pools that are on `localhost`. -[source,oac_no_warn] +[source] ---- asadmin> list-jdbc-connection-pools sample_derby_pool2 @@ -451,19 +453,16 @@ Before You Begin Before you can contact a connection pool, the connection pool must be created with authentication, and the server or database must be running. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Ping a connection pool by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Ping a connection pool by using the link:../reference-manual/ping-connection-pool.html#GSRFM00214[`ping-connection-pool`] subcommand. [[GSADG00216]][[ggpcs]] - - Example 11-5 Contacting a Connection Pool This example tests to see if the `DerbyPool` connection pool is usable. -[source,oac_no_warn] +[source] ---- asadmin> ping-connection-pool DerbyPool Command ping-connection-pool executed successfully @@ -496,22 +495,19 @@ that the transactions associated with these connections are lost and must be retried. The subcommand then recreates the initial connections for the pool, and restores the pool to its steady pool size. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Reset a connection pool by using +1. Ensure that the server is running. Remote subcommands require a running server. +2. Reset a connection pool by using theolink:GSRFM00135[`flush-connection-pool`] subcommand. [[GSADG00217]][[gjirk]] - - Example 11-6 Resetting (Flushing) a Connection Pool This example resets the JDBC connection pool named `__TimerPool` to its steady pool size. -[source,oac_no_warn] +[source] ---- -asadmin> flush-connection-pool __TimerPool +asadmin> flush-connection-pool __TimerPool Command flush-connection-pool executed successfully. ---- @@ -531,23 +527,28 @@ You can change all of the settings for an existing pool except its name. Use the `get` and `set` subcommands to view and change the values of the JDBC connection pool properties. -1. List the JDBC connection pools by using the +1. List the JDBC connection pools by using the link:../reference-manual/list-jdbc-connection-pools.html#GSRFM00173[`list-jdbc-connection-pools`] subcommand. -2. View the attributes of the JDBC connection pool by using the get -subcommand. + -For example: + -[source,oac_no_warn] +2. View the attributes of the JDBC connection pool by using the get +subcommand. ++ +For example: ++ +[source] ---- asadmin get resources.jdbc-connection-pool.DerbyPool.property ---- -3. Set the attribute of the JDBC connection pool by using the set -subcommand. + -For example: + -[source,oac_no_warn] +3. Set the attribute of the JDBC connection pool by using the set +subcommand. ++ +For example: ++ +[source] ---- asadmin set resources.jdbc-connection-pool.DerbyPool.steady-pool-size=9 ---- -4. If needed, restart the server. + +4. If needed, restart the server. ++ Some parameters require server restart. See link:overview.html#ghciy[Configuration Changes That Require Restart]. @@ -575,23 +576,20 @@ Before You Begin Before deleting a JDBC connection pool, all associations to the resource must be removed. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the JDBC connection pools by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the JDBC connection pools by using the link:../reference-manual/list-jdbc-connection-pools.html#GSRFM00173[`list-jdbc-connection-pools`] subcommand. -3. If necessary, notify users that the JDBC connection pool is being +3. If necessary, notify users that the JDBC connection pool is being deleted. -4. Delete the connection pool by using the +4. Delete the connection pool by using the link:../reference-manual/delete-jdbc-connection-pool.html#GSRFM00088[`delete-jdbc-connection-pool`] subcommand. [[GSADG00218]][[ggpis]] - - Example 11-7 Deleting a JDBC Connection Pool This example deletes the JDBC connection pool named `DerbyPool`. -[source,oac_no_warn] +[source] ---- asadmin> delete-jdbc-connection-pool jdbc/DerbyPool Command delete-jdbc-connection-pool executed successfully. @@ -647,8 +645,9 @@ button in the Administration Console. * Specify it using the `--property` option in the `create-jdbc-connection-pool` subcommand. For more information, see link:../reference-manual/create-jdbc-connection-pool.html#GSRFM00036[`create-jdbc-connection-pool`(1)]. -* Set it using the `set` subcommand. For example: + -[source,oac_no_warn] +* Set it using the `set` subcommand. For example: ++ +[source] ---- asadmin set resources.jdbc-connection-pool.pool-name.property.dynamic-reconfiguration-wait-timeout-in-seconds=15 ---- @@ -676,8 +675,9 @@ click the Help button in the Administration Console. `asadmin create-jdbc-connection-pool` command. For more information, see link:../reference-manual/create-jdbc-connection-pool.html#GSRFM00036[`create-jdbc-connection-pool`(1)]. * Specify the `init-sql` option in the `asadmin set` command. For -example: + -[source,oac_no_warn] +example: ++ +[source] ---- asadmin set domain1.resources.jdbc-connection-pool.DerbyPool.init-sql="sql-string" ---- @@ -722,8 +722,9 @@ of the following ways: `create-jdbc-connection-pool` subcommand. For more information, see link:../reference-manual/create-jdbc-connection-pool.html#GSRFM00036[`create-jdbc-connection-pool`(1)]. * Specify the `statement-leak-timeout-in-seconds` option in the `set` -subcommand. For example: + -[source,oac_no_warn] +subcommand. For example: ++ +[source] ---- asadmin set resources.jdbc-connection-pool.pool-name.statement-leak-timeout-in-seconds=300 ---- @@ -744,8 +745,9 @@ pool to a `true` value in one of the following ways: `create-jdbc-connection-pool` subcommand. For more information, see link:../reference-manual/create-jdbc-connection-pool.html#GSRFM00036[`create-jdbc-connection-pool`(1)]. * Specify the `statement-leak-reclaim` option in the `set` subcommand. -For example: + -[source,oac_no_warn] +For example: ++ +[source] ---- asadmin set resources.jdbc-connection-pool.pool-name.statement-leak-reclaim=true ---- @@ -772,8 +774,9 @@ information, click the Help button in the Administration Console. `asadmin create-jdbc-connection-pool` command. For more information, see link:../reference-manual/create-jdbc-connection-pool.html#GSRFM00036[`create-jdbc-connection-pool`(1)]. * Specify the `statement-cache-size` option in the `asadmin set` -command. For example: + -[source,oac_no_warn] +command. For example: ++ +[source] ---- asadmin set domain1.resources.jdbc-connection-pool.DerbyPool.statement-cache-size=10 ---- @@ -800,8 +803,9 @@ information, click the Help button in the Administration Console. `asadmin create-jdbc-connection-pool` command. For more information, see link:../reference-manual/create-jdbc-connection-pool.html#GSRFM00036[`create-jdbc-connection-pool`(1)]. * Specify the `sql-trace-listeners` option in the `asadmin set` command. -For example: + -[source,oac_no_warn] +For example: ++ +[source] ---- asadmin set domain1.resources.jdbc-connection-pool.DerbyPool.sql-trace-listeners=listeners ---- @@ -819,12 +823,12 @@ file. The module name under which the SQL operation is logged is messages along with the module name to enable easy filtering of the SQL logs. A sample SQL trace record looks like this: -[source,oac_no_warn] +[source] ---- [#|2009-11-27T15:46:52.202+0530|FINE|glassfishv3.0|jakarta.enterprise.resource.sqltrace.com.sun.gjc.util |_ThreadID=29;_ThreadName=Thread-1;ClassName=com.sun.gjc.util.SQLTraceLogger;MethodName=sqlTrace; -|ThreadID=77 | ThreadName=p: thread-pool-1; w: 6 | TimeStamp=1259317012202 -| ClassName=com.sun.gjc.spi.jdbc40.PreparedStatementWrapper40 | MethodName=executeUpdate +|ThreadID=77 | ThreadName=p: thread-pool-1; w: 6 | TimeStamp=1259317012202 +| ClassName=com.sun.gjc.spi.jdbc40.PreparedStatementWrapper40 | MethodName=executeUpdate | arg[0]=insert into table1(colName) values(100) | arg[1]=columnNames | |#] ---- @@ -852,8 +856,9 @@ button in the Administration Console. * Specify them using the `--property` option in the `create-jdbc-connection-pool` subcommand. For more information, see link:../reference-manual/create-jdbc-connection-pool.html#GSRFM00036[`create-jdbc-connection-pool`(1)]. -* Set them using the `set` subcommand. For example: + -[source,oac_no_warn] +* Set them using the `set` subcommand. For example: ++ +[source] ---- asadmin set resources.jdbc-connection-pool.pool-name.property.time-to-keep-queries-in-minutes=10 ---- @@ -917,22 +922,20 @@ Before creating a JDBC resource, you must first create a JDBC connection pool. For instructions, see link:#ggnfv[To Create a JDBC Connection Pool]. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create a JDBC resource by using the -link:../reference-manual/create-jdbc-resource.html#GSRFM00037[`create-jdbc-resource`] subcommand. + +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create a JDBC resource by using the +link:../reference-manual/create-jdbc-resource.html#GSRFM00037[`create-jdbc-resource`] subcommand. ++ Information about properties for the subcommand is included in this help page. -3. If necessary, notify users that the new resource has been created. +3. If necessary, notify users that the new resource has been created. [[GSADG00219]][[ggplj]] - - Example 11-8 Creating a JDBC Resource This example creates a JDBC resource named `DerbyPool`. -[source,oac_no_warn] +[source] ---- asadmin> create-jdbc-resource --connectionpoolid DerbyPool jdbc/DerbyPool Command create-jdbc-resource executed successfully. @@ -953,19 +956,16 @@ To List JDBC Resources Use the `list-jdbc-resources` subcommand in remote mode to list the existing JDBC resources. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List JDBC resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List JDBC resources by using the link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`list-jdbc-resources`] subcommand. [[GSADG00220]][[ggpgi]] - - Example 11-9 Listing JDBC Resources This example lists JDBC resources for `localhost`. -[source,oac_no_warn] +[source] ---- asadmin> list-jdbc-resources jdbc/__TimerPool @@ -990,20 +990,19 @@ To Update a JDBC Resource You can enable or disable a JDBC resource by using the `set` subcommand. The JDBC resource is identified by its dotted name. -1. List JDBC resources by using the +1. List JDBC resources by using the link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`list-jdbc-resources`] subcommand. -2. Modify the values for the specified JDBC resource by using the -link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. + +2. Modify the values for the specified JDBC resource by using the +link:../reference-manual/set.html#GSRFM00226[`set`] subcommand. ++ For example: [[GSADG00221]][[gjkrz]] - - Example 11-10 Updating a JDBC Resource This example changes the `res1` enabled setting to false. -[source,oac_no_warn] +[source] ---- asadmin>set resources.jdbc-resource.res1.enabled=false ---- @@ -1024,22 +1023,19 @@ Before You Begin Before deleting a JDBC resource, all associations with this resource must be removed. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List JDBC resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List JDBC resources by using the link:../reference-manual/list-jdbc-resources.html#GSRFM00174[`list-jdbc-resources`] subcommand. -3. If necessary, notify users that the JDBC resource is being deleted. -4. Delete a JDBC resource by using the +3. If necessary, notify users that the JDBC resource is being deleted. +4. Delete a JDBC resource by using the link:../reference-manual/delete-jdbc-resource.html#GSRFM00089[`delete-jdbc-resource`] subcommand. [[GSADG00222]][[ggpga]] - - Example 11-11 Deleting a JDBC Resource This example deletes a JDBC resource named `DerbyPool`. -[source,oac_no_warn] +[source] ---- asadmin> delete-jdbc-resource jdbc/DerbyPool Command delete-jdbc-resource executed successfully. @@ -1072,19 +1068,22 @@ link:#ggnda[To Create a JDBC Resource]. Use the following procedure to enable the preconfigured `jdbc/__default` resource for a clustered GlassFish Server environment. -1. Create the `jdbc/__default` resource reference for the cluster. + -[source,oac_no_warn] +1. Create the `jdbc/__default` resource reference for the cluster. ++ +[source] ---- asadmin create-resource-ref --target cluster-name jdbc/__default ---- -2. Enable the resource on the DAS that manages the cluster. + -[source,oac_no_warn] +2. Enable the resource on the DAS that manages the cluster. ++ +[source] ---- asadmin set resources.jdbc-connection-pool.DerbyPool.property.serverName=DAS-machine-name ---- This step is only required if the cluster includes remote instances. -3. Restart the DAS and the target cluster(s). + -[source,oac_no_warn] +3. Restart the DAS and the target cluster(s). ++ +[source] ---- asadmin stop-cluster cluster-name asadmin stop-domain domain-name @@ -1118,14 +1117,12 @@ link:#beamw[Configuration Specifics for JDBC Drivers]. [NOTE] -======================================================================= - +==== Because the drivers and databases supported by the GlassFish Server are constantly being updated, and because database vendors continue to upgrade their products, always check with Oracle technical support for the latest database support information. - -======================================================================= +==== [[gkpci]][[GSADG00672]][[making-the-jdbc-driver-jar-files-accessible]] @@ -1202,7 +1199,7 @@ The JAR files for the DB2 driver are `db2jcc.jar`, `db2jcc_license_cu.jar`, and `db2java.zip`. Set your environment variables . For example: -[source,oac_no_warn] +[source] ---- LD_LIBRARY_PATH=/usr/db2user/sqllib/lib:${Java EE.home}/lib DB2DIR=/opt/IBM/db2/V8.2 @@ -1267,8 +1264,9 @@ Configure the connection pool using the following settings: * Name: Use this name when you configure the JDBC resource later. * Resource Type: Specify the appropriate value. * Database Vendor: Apache Derby -* DataSource Classname: Specify one of the following: + -[source,oac_no_warn] +* DataSource Classname: Specify one of the following: ++ +[source] ---- org.apache.derby.jdbc.ClientDataSource40 org.apache.derby.jdbc.ClientXADataSource40 @@ -1283,13 +1281,15 @@ is different from the default. ** `databaseName` - Specify the name of the database. -** `user` - Specify the database user. + +** `user` - Specify the database user. ++ This is only necessary if the Apache Derby database is configured to use authentication. The Apache Derby database does not use authentication by default. When the user is provided, it is the name of the schema where the tables reside. -** `password` - Specify the database password. + +** `password` - Specify the database password. ++ This is only necessary if the Apache Derby database is configured to use authentication. @@ -1305,8 +1305,9 @@ using the following settings: * Name: Use this name when you configure the JDBC resource later. * Resource Type: Specify the appropriate value. * Database Vendor: MySql -* DataSource Classname: + -[source,oac_no_warn] +* DataSource Classname: ++ +[source] ---- com.mysql.jdbc.jdbc2.optional.MysqlDataSource com.mysql.jdbc.jdbc2.optional.MysqlXADataSource @@ -1336,7 +1337,7 @@ that the `ORACLE_HOME` property is set. To make the Oracle driver behave in a Java EE-compliant manner, you must define the following JVM property: -[source,oac_no_warn] +[source] ---- -Doracle.jdbc.J2EE13Compliant=true ---- @@ -1346,8 +1347,9 @@ Configure the connection pool using the following settings: * Name: Use this name when you configure the JDBC resource later. * Resource Type: Specify the appropriate value. * Database Vendor: Oracle -* DataSource Classname: Specify one of the following: + -[source,oac_no_warn] +* DataSource Classname: Specify one of the following: ++ +[source] ---- oracle.jdbc.pool.OracleDataSource oracle.jdbc.xa.client.OracleXADataSource @@ -1368,7 +1370,7 @@ The JAR file for the Oracle 11 database driver is `ojdbc6.jar`. To make the Oracle driver behave in a Java EE-compliant manner, you must define the following JVM property: -[source,oac_no_warn] +[source] ---- -Doracle.jdbc.J2EE13Compliant=true ---- @@ -1378,8 +1380,9 @@ Configure the connection pool using the following settings: * Name: Use this name when you configure the JDBC resource later. * Resource Type: Specify the appropriate value. * Database Vendor: Oracle -* DataSource Classname: Specify one of the following: + -[source,oac_no_warn] +* DataSource Classname: Specify one of the following: ++ +[source] ---- oracle.jdbc.pool.OracleDataSource oracle.jdbc.xa.client.OracleXADataSource @@ -1388,11 +1391,11 @@ oracle.jdbc.xa.client.OracleXADataSource ** `user` - Set as appropriate. -** `password` - Set as appropriate. + +** `password` - Set as appropriate. ++ [NOTE] -======================================================================= - +==== For this driver, the `XAResource.recover` method repeatedly returns the same set of in-doubt Xids regardless of the input flag. According to the XA specifications, the Transaction Manager initially calls this method @@ -1409,8 +1412,7 @@ certain Oracle permissions: ** SELECT permission on DBA_PENDING_TRANSACTIONS, PENDING_TRANS$, DBA_2PC_PENDING and DBA_2PC_NEIGHBORS. ** EXECUTE permissions on DBMS_XA and DBMS_SYSTEM. - -======================================================================= +==== [[gjksj]][[GSADG00755]][[postgresql-type-4-driver]] @@ -1474,8 +1476,9 @@ Configure the connection pool using the following settings: * Name: Use this name when you configure the JDBC resource later. * Resource Type: Specify the appropriate value. * Database Vendor: DataDirect-Informix -* DataSource Classname: Specify one of the following: + -[source,oac_no_warn] +* DataSource Classname: Specify one of the following: ++ +[source] ---- com.informix.jdbcx.IfxDataSource com.informix.jdbcx.IfxXADataSource @@ -1557,7 +1560,7 @@ The JAR file for the DataDirect driver is `oracle.jar`. To make the Oracle driver behave in a Java EE-compliant manner, you must define the following JVM property: -[source,oac_no_warn] +[source] ---- -Doracle.jdbc.J2EE13Compliant=true ---- @@ -1606,14 +1609,12 @@ server. [NOTE] -======================================================================= - +==== In some situations, using this driver can cause exceptions to be thrown because the driver creates a stored procedure for every parameterized PreparedStatement by default. If this situation arises, add the property `PrepareMethod`, setting its value to `direct`. - -======================================================================= +==== [[beane]][[GSADG00762]][[inet-oraxo-driver-for-oracle-database]] @@ -1639,14 +1640,15 @@ server. ** `password` - Specify the database password. -** `serviceName` - Specify the URL of the database. The syntax is as -follows: + -[source,oac_no_warn] +** `serviceName` - Specify the URL of the database. The syntax is as follows: ++ +[source] ---- jdbc:inetora:server:port:dbname ---- -For example: + -[source,oac_no_warn] +For example: ++ +[source] ---- jdbc:inetora:localhost:1521:payrolldb ---- @@ -1718,8 +1720,9 @@ connection pool using the following settings: * Name: Use this name when you configure the JDBC resource later. * Resource Type: Specify the appropriate value. * Database Vendor: Sybase -* DataSource Classname: Specify one of the following: + -[source,oac_no_warn] +* DataSource Classname: Specify one of the following: ++ +[source] ---- com.sybase.jdbc4.jdbc.SybDataSource com.sybase.jdbc4.jdbc.SybXADataSource diff --git a/docs/administration-guide/src/main/jbake/content/jms.adoc b/docs/administration-guide/src/main/jbake/content/jms.adoc index eea7e009a8c3..9583e13c1548 100644 --- a/docs/administration-guide/src/main/jbake/content/jms.adoc +++ b/docs/administration-guide/src/main/jbake/content/jms.adoc @@ -4,6 +4,7 @@ title=Administering the Java Message Service (JMS) next=jndi.html prev=javamail.html ~~~~~~ + Administering the Java Message Service (JMS) ============================================ @@ -69,18 +70,18 @@ JMS Hosts:: JMS hosts are the message servers that host destinations, store messages, and interact with applications to send and receive messages across connections. In Message Queue, JMS hosts are called brokers. + - The JMS service supports these types of JMS hosts: + + The JMS service supports these types of JMS hosts: + * Embedded type, in which the JMS host runs in the same JVM as the - GlassFish instance; its configuration and lifecycle are managed by the - JMS service + GlassFish instance; its configuration and lifecycle are managed by the JMS service. * Local type, in which the JMS host runs separately on the same host - as the GlassFish instance; its configuration and lifecycle are managed - by the JMS service + as the GlassFish instance; its configuration and lifecycle are managed by the JMS service. * Remote type, in which the JMS host represents a Message Queue broker - or broker cluster that is external to the JMS service; its operation - is managed using Message Queue administrative tools + - For more information about JMS host types, see link:#giplw[About JMS - Host Types]. + or broker cluster that is external to the JMS service; its operation + is managed using Message Queue administrative tools. + ++ +For more information about JMS host types, see link:#giplw[About JMS Host Types]. JMS Connection Factory Resources:: JMS connection factory resources house the information that applications use to connect to a JMS provider. For each JMS connection @@ -135,7 +136,7 @@ JMS service configuration by using the Java Message Service page for the configuration in the Administration Console, or by using a `set` subcommand of the following form: -[source,oac_no_warn] +[source] ---- set configs.config.config-name.jms-service.attribute-name=attribute-value ---- @@ -174,7 +175,8 @@ The attributes you can set are: interval does not give a JMS host time to recover. If it is too long, the reconnect might represent an unacceptable delay. `addresslist-behavior`:: - The order of connection attempts. Available choices are: + + The order of connection attempts. Available choices are: ++ `random`;; Select a JMS host from the AddressList randomly. If there are many clients attempting a connection using the same connection factory, @@ -196,13 +198,11 @@ The attributes you can set are: [NOTE] -======================================================================= - +==== After making changes to the JMS service configuration, GlassFish Server instances that use the configuration must be restarted in order for the changes to be propagated. - -======================================================================= +==== [[gkxgf]][[GSADG00774]][[setting-message-queue-broker-properties-in-the-jms-service-configuration]] @@ -216,7 +216,7 @@ the Java Message Service page for the configuration in the Administration Console, or by using a `set` subcommand of the following form: -[source,oac_no_warn] +[source] ---- set configs.config.config-name.jms-service.property.broker-property-name=value ---- @@ -227,13 +227,11 @@ property, specify `imq\\.system\\.max_count` in the `set` subcommand. [NOTE] -======================================================================= - +==== You can also set broker properties in the JMS host. If you set the same broker property in both the JMS service configuration and the JMS host, the value specified in the JMS host is used. - -======================================================================= +==== [[gipbg]][[GSADG00597]][[administering-jms-hosts]] @@ -275,12 +273,14 @@ Embedded Type:: When the JMS service configuration's `type` attribute is `EMBEDDED`, the MQ broker is co-located in the same JVM as the GlassFish server instance it services. The JMS service starts it in-process and manages - its configuration and lifecycle. + + its configuration and lifecycle. ++ For this type, the JMS service uses lazy initialization to start the broker when the first JMS operation is requested instead of immediately when the GlassFish instance is started. If necessary, you can force startup of the broker by using the - link:../reference-manual/jms-ping.html#GSRFM00144[`jms-ping`] command. + + link:../reference-manual/jms-ping.html#GSRFM00144[`jms-ping`] command. ++ Additionally, if the GlassFish instance is a standalone instance (not a clustered instance), JMS operations use a Message Queue feature called direct mode to bypass the networking stack, leading to @@ -290,9 +290,11 @@ Local Type:: JMS service starts the MQ broker specified in the configuration as the default JMS host in a separate process on the same host as the GlassFish server instance. The JMS service manages its configuration - and lifecycle. + + and lifecycle. ++ For this type, the JMS service starts the broker immediately when the - GlassFish instance is started. + + GlassFish instance is started. ++ The JMS service provides the Message Queue broker an additional port to start the RMI registry. This port number is equal to the broker's JMS port plus 100. For example, if the JMS port number is 37676, then @@ -325,13 +327,15 @@ This location depends on which GlassFish instance the JMS host is servicing: * For `server`, the Domain Administration Server (DAS), the -`IMQ_VARHOME` location is: + -[source,oac_no_warn] +`IMQ_VARHOME` location is: ++ +[source] ---- domain-root-dir/domain-dir/imq ---- -* For any other GlassFish instance, the `IMQ_VARHOME` location is: + -[source,oac_no_warn] +* For any other GlassFish instance, the `IMQ_VARHOME` location is: ++ +[source] ---- as-install/nodes/node-name/instance-name/imq ---- @@ -345,14 +349,12 @@ as-install`/nodes/`node-name`/`instance-name`/imq/instances/`mq-instance-name`/l [NOTE] -======================================================================= - +==== When using Message Queue utilities on the Windows platform, you must explicitly use the Windows executable (`.exe`) versions of the utilities, even when running command shells such as Cygwin. For example, instead of running `imqcmd`, you must run `imqcmd.exe`. - -======================================================================= +==== [[gipbh]][[GSADG00486]][[to-create-a-jms-host]] @@ -366,11 +368,13 @@ replacing it or creating additional JMS hosts is not often necessary and is a task for advanced users. Use the `create-jms-host` subcommand in remote `asadmin` mode to create an additional JMS host. -1. Ensure that the server is running. + +1. Ensure that the server is running. ++ Remote `asadmin` subcommands require a running server. -2. Create the JMS host by using the link:../reference-manual/create-jms-host.html#GSRFM00039[`create-jms-host`] -subcommand: + -[source,oac_no_warn] +2. Create the JMS host by using the link:../reference-manual/create-jms-host.html#GSRFM00039[`create-jms-host`] +subcommand: ++ +[source] ---- asadmin> create-jms-host --mqhost hostName --mqport portNumber --mquser adminUser --mqpassword adminPassword --target glassfishTarget @@ -389,8 +393,9 @@ asadmin> create-jms-host --mqhost hostName --mqport portNumber For details, see link:../reference-manual/create-jms-host.html#GSRFM00039[`create-jms-host`(1)]. `--property`:: A list of one or more Message Queue broker properties to configure the - broker. The list is colon-separated (`:`) and has the form: + -[source,oac_no_warn] + broker. The list is colon-separated (`:`) and has the form: ++ +[source] ---- prop1Name=prop1Value:prop2Name=prop2Value:... ---- @@ -398,18 +403,15 @@ prop1Name=prop1Value:prop2Name=prop2Value:... If a broker property name includes dots, preface the dots with two backslashes (`\\`); for example, to include the `imq.system.max_count` property, specify `imq\\.system\\.max_count` in the `--property` - option. + - -[width="100%",cols="100%",] -|======================================================================= -a| -Note: + option. ++ +[NOTE] +==== You can also set broker properties in the JMS service configuration. If you set the same broker property in both the JMS host and the JMS service configuration, the value specified in the JMS host is used. - -|======================================================================= +==== `--force`:: Specifies whether the subcommand overwrites the existing JMS host of @@ -418,13 +420,11 @@ jms-host-name:: The unique name of the JMS host. [[GSADG00271]][[gipbb]] - - Example 17-1 Creating a JMS Host This example creates a JMS host named `MyNewHost`. -[source,oac_no_warn] +[source] ---- asadmin> create-jms-host --mqhost pigeon --mqport 7677 --mquser admin --mqpassword admin MyNewHost @@ -447,19 +447,18 @@ To List JMS Hosts Use the `list-jms-hosts` subcommand in remote `asadmin` mode to list the existing JMS hosts. -1. Ensure that the server is running. + +1. Ensure that the server is running. ++ Remote `asadmin` subcommands require a running server. -2. List the JMS hosts by using the link:../reference-manual/list-jms-hosts.html#GSRFM00176[`list-jms-hosts`] +2. List the JMS hosts by using the link:../reference-manual/list-jms-hosts.html#GSRFM00176[`list-jms-hosts`] subcommand. [[GSADG00272]][[gipdw]] - - Example 17-2 Listing JMS Hosts The following subcommand lists the existing JMS hosts. -[source,oac_no_warn] +[source] ---- asadmin> list-jms-hosts default_JMS_host @@ -475,19 +474,22 @@ To Update a JMS Host Use the `set` subcommand in remote `asadmin` mode to update an existing JMS host. -1. Ensure that the server is running. + +1. Ensure that the server is running. ++ Remote `asadmin` subcommands require a running server. -2. Use the link:../reference-manual/get.html#GSRFM00139[`get`] subcommand to list the current -attribute values of the desired JMS host: + -[source,oac_no_warn] +2. Use the link:../reference-manual/get.html#GSRFM00139[`get`] subcommand to list the current +attribute values of the desired JMS host: ++ +[source] ---- asadmin> get configs.config.config-name.jms-service.jms-host.jms-host-name.* ---- For information about JMS host attributes, see link:../reference-manual/create-jms-host.html#GSRFM00039[`create-jms-host`(1)]. -3. Use the link:../reference-manual/set.html#GSRFM00226[`set`] subcommand to modify a JMS host -attribute: + -[source,oac_no_warn] +3. Use the link:../reference-manual/set.html#GSRFM00226[`set`] subcommand to modify a JMS host +attribute: ++ +[source] ---- asadmin> set configs.config.config-name.jms-service.jmshost. jms-host-name.attribute-name=attribute-value @@ -503,32 +505,28 @@ The attributes you can set are::: The password of the administrative user of the Message Queue broker. `property.`broker-property-name:: A Message Queue broker property. The property, and the value assigned - to it, are used to configure the Message Queue broker. + + to it, are used to configure the Message Queue broker. ++ If the broker property name includes dots, preface the dots with two backslashes (`\\`); for example, to include the `imq.system.max_count` - property, specify `imq\\.system\\.max_count` in the `set` subcommand. + - -[width="100%",cols="100%",] -|======================================================================= -a| -Note: + property, specify `imq\\.system\\.max_count` in the `set` subcommand. ++ +[NOTE] +==== You can also set broker properties in the JMS service configuration. If you set the same broker property in both the JMS host and the JMS service configuration, the value specified in the JMS host is used. - -|======================================================================= +==== [[GSADG00273]][[givlz]] - - Example 17-3 Updating a JMS Host This example changes the value of the `host` attribute of the JMS host `default_JMS_Host`. By default this value is `localhost`. -[source,oac_no_warn] +[source] ---- asadmin> set configs.config.server-config.jms-service.jms-host.default_JMS_host.host= "server1.middleware.example.com" @@ -543,21 +541,20 @@ Use the `delete-jms-host` subcommand in remote `asadmin` mode to delete a JMS host from the JMS service. If you delete the only JMS host, the JMS service will not be able to start until you create a new JMS host. -1. Ensure that the server is running. + +1. Ensure that the server is running. ++ Remote `asadmin` subcommands require a running server. -2. List the JMS hosts by using the link:../reference-manual/list-jms-hosts.html#GSRFM00176[`list-jms-hosts`] +2. List the JMS hosts by using the link:../reference-manual/list-jms-hosts.html#GSRFM00176[`list-jms-hosts`] subcommand. -3. Delete a JMS host by using the link:../reference-manual/delete-jms-host.html#GSRFM00091[`delete-jms-host`] +3. Delete a JMS host by using the link:../reference-manual/delete-jms-host.html#GSRFM00091[`delete-jms-host`] subcommand. [[GSADG00274]][[gipbj]] - - Example 17-4 Deleting a JMS Host This example deletes a JMS host named `MyNewHost`. -[source,oac_no_warn] +[source] ---- asadmin> delete-jms-host MyNewHost Command delete-jms-host executed successfully. @@ -647,16 +644,14 @@ a JMS connection factory resource or a destination resource. [TIP] -======================================================================= - +==== To specify the `addresslist` property (in the format `host:mqport,host2:mqport,host3:mqport`) for the `asadmin create-jms-resource` command, escape the : by using `\\`. For example, `host1\\:mqport,host2\\:mqport,host3\\:mpqport`. For more information about using escape characters, see the olink:GSRFM00263[`asadmin`(1M)] help page. - -======================================================================= +==== To update a JMS connection factory, use the `set` subcommand for the @@ -667,21 +662,22 @@ To update a destination, use the `set` subcommand for the admin object resource. See link:connectors.html#giots[To Update an Administered Object]. -1. Ensure that the server is running. + +1. Ensure that the server is running. ++ Remote `asadmin` subcommands require a running server. -2. Create a JMS resource by using the -link:../reference-manual/create-jms-resource.html#GSRFM00040[`create-jms-resource`] command. + +2. Create a JMS resource by using the +link:../reference-manual/create-jms-resource.html#GSRFM00040[`create-jms-resource`] command. ++ Information about the properties for the subcommand is included in this help page. -3. If needed, restart the server. + +3. If needed, restart the server. ++ Some properties require server restart. See link:overview.html#ghciy[Configuration Changes That Require Restart]. If your server needs to be restarted, see link:domains.html#ginqj[To Restart a Domain]. [[GSADG00275]][[giovy]] - - Example 17-5 Creating a JMS Connection Factory This example creates a connection factory resource of type @@ -691,7 +687,7 @@ on the connection factory so that it can be used for durable subscriptions. The JNDI name for a JMS resource customarily includes the `jms/` naming subcontext. -[source,oac_no_warn] +[source] ---- asadmin> create-jms-resource --restype jakarta.jms.ConnectionFactory --description "connection factory for durable subscriptions" @@ -700,16 +696,14 @@ Command create-jms-resource executed successfully. ---- [[GSADG00276]][[giovn]] - - Example 17-6 Creating a JMS Destination This example creates a destination resource whose JNDI name is `jms/MyQueue`. -[source,oac_no_warn] +[source] ---- -asadmin> create-jms-resource --restype jakarta.jms.Queue +asadmin> create-jms-resource --restype jakarta.jms.Queue --property Name=PhysicalQueue jms/MyQueue Command create-jms-resource executed successfully. ---- @@ -729,20 +723,19 @@ To List JMS Resources Use the `list-jms-resources` subcommand in remote `asadmin` mode to list the existing connection factory and destination resources. -1. Ensure that the server is running. + +1. Ensure that the server is running. ++ Remote `asadmin` subcommands require a running server. -2. List the existing JMS resources by using the +2. List the existing JMS resources by using the link:../reference-manual/list-jms-resources.html#GSRFM00177[`list-jms-resources`] subcommand. [[GSADG00277]][[giovz]] - - Example 17-7 Listing All JMS Resources This example lists all the existing JMS connection factory and destination resources. -[source,oac_no_warn] +[source] ---- asadmin> list-jms-resources jms/Queue @@ -753,17 +746,15 @@ Command list-jms-resources executed successfully ---- [[GSADG00278]][[giovq]] - - Example 17-8 Listing a JMS Resources of a Specific Type This example lists the resources for the resource type `javax`. -[source,oac_no_warn] +[source] ---- -asadmin> list-jms-resources --restype jakarta.jms.TopicConnectionFactory -jms/DurableTopicConnectionFactory -jms/TopicConnectionFactory +asadmin> list-jms-resources --restype jakarta.jms.TopicConnectionFactory +jms/DurableTopicConnectionFactory +jms/TopicConnectionFactory Command list-jms-resources executed successfully. ---- @@ -789,21 +780,20 @@ Before You Begin Ensure that you remove all references to the specified JMS resource before running this subcommand. -1. Ensure that the server is running. + +1. Ensure that the server is running. ++ Remote `asadmin` subcommands require a running server. -2. List the existing JMS resources by using the +2. List the existing JMS resources by using the link:../reference-manual/list-jms-resources.html#GSRFM00177[`list-jms-resources`] subcommand. -3. Delete the JMS resource by using the +3. Delete the JMS resource by using the link:../reference-manual/delete-jms-resource.html#GSRFM00092[`delete-jms-resource`] subcommand. [[GSADG00279]][[giovi]] - - Example 17-9 Deleting a JMS Resource This example deletes the `jms/Queue` resource. -[source,oac_no_warn] +[source] ---- asadmin> delete-jms-resource jms/Queue Command delete-jms-resource executed successfully @@ -864,28 +854,29 @@ than a server object, you use Message Queue broker commands to update properties. For information on Message Queue properties, see the link:../../openmq/mq-admin-guide/toc.html#GMADG[Open Message Queue Administration Guide]. -1. Ensure that the server is running. + +1. Ensure that the server is running. ++ Remote `asadmin` subcommands require a running server. -2. Create a JMS physical destination by using the -link:../reference-manual/create-jmsdest.html#GSRFM00038[`create-jmsdest`] subcommand. + +2. Create a JMS physical destination by using the +link:../reference-manual/create-jmsdest.html#GSRFM00038[`create-jmsdest`] subcommand. ++ Information about the properties for the subcommand is included in this help page. -3. If needed, restart the server. + +3. If needed, restart the server. ++ Some properties require server restart. See link:overview.html#ghciy[Configuration Changes That Require Restart]. If your server needs to be restarted, see link:domains.html#ginqj[To Restart a Domain]. [[GSADG00280]][[gioxt]] - - Example 17-10 Creating a JMS Physical Destination This example creates a queue named `PhysicalQueue`. -[source,oac_no_warn] +[source] ---- -asadmin> create-jmsdest --desttype queue --property +asadmin> create-jmsdest --desttype queue --property User=public:Password=public PhysicalQueue Command create-jmsdest executed successfully. ---- @@ -905,23 +896,22 @@ To List JMS Physical Destinations Use the `list-jmsdest` subcommand in remote `asadmin` mode to list the existing JMS physical destinations. -1. Ensure that the server is running. + +1. Ensure that the server is running. ++ Remote `asadmin` subcommands require a running server. -2. List the existing JMS physical destinations by using the +2. List the existing JMS physical destinations by using the link:../reference-manual/list-jmsdest.html#GSRFM00175[`list-jmsdest`] subcommand. [[GSADG00281]][[gioxo]] - - Example 17-11 Listing JMS Physical Destinations This example lists the physical destinations for the default server instance. -[source,oac_no_warn] +[source] ---- asadmin> list-jmsdest -PhysicalQueue queue {} +PhysicalQueue queue {} PhysicalTopic topic {} Command list-jmsdest executed successfully. ---- @@ -942,24 +932,24 @@ Use the `flush-jmsdest` subcommand in remote `asadmin` mode to purge the messages from a physical destination in the specified target's JMS service configuration. -1. Ensure that the server is running. + +1. Ensure that the server is running. ++ Remote `asadmin` subcommands require a running server. -2. Purge messages from the a JMS physical destination by using the +2. Purge messages from the a JMS physical destination by using the link:../reference-manual/flush-jmsdest.html#GSRFM00136[`flush-jmsdest`] subcommand. -3. If needed, restart the server. + +3. If needed, restart the server. ++ Some properties require server restart. See link:overview.html#ghciy[Configuration Changes That Require Restart]. If your server needs to be restarted, see link:domains.html#ginqj[To Restart a Domain]. [[GSADG00282]][[giows]] - - Example 17-12 Flushing Messages From a JMS Physical Destination This example purges messages from the queue named `PhysicalQueue`. -[source,oac_no_warn] +[source] ---- asadmin> flush-jmsdest --desttype queue PhysicalQueue Command flush-jmsdest executed successfully @@ -980,21 +970,20 @@ To Delete a JMS Physical Destination Use the `delete-jmsdest` subcommand in remote `asadmin` mode to remove the specified JMS physical destination. -1. Ensure that the server is running. + +1. Ensure that the server is running. ++ Remote `asadmin` subcommands require a running server. -2. List the existing JMS physical destinations by using the +2. List the existing JMS physical destinations by using the link:../reference-manual/list-jmsdest.html#GSRFM00175[`list-jmsdest`] subcommand. -3. Delete the physical resource by using the +3. Delete the physical resource by using the link:../reference-manual/delete-jmsdest.html#GSRFM00090[`delete-jmsdest`] subcommand. [[GSADG00283]][[gioxx]] - - Example 17-13 Deleting a Physical Destination This example deletes the queue named `PhysicalQueue`. -[source,oac_no_warn] +[source] ---- asadmin> delete-jmsdest --desttype queue PhysicalQueue Command delete-jmsdest executed successfully @@ -1031,17 +1020,23 @@ Restarting an Embedded or Local Broker That Has Failed:: servicing. Changing the Admin User Password for an Embedded or Local Broker:: Follow these steps to change the `admin` user password for an Embedded - or Local broker: + - 1. [[CHDDHDIE]] + + or Local broker: ++ + 1. [[CHDDHDIE]] ++ Make sure the broker is running. - 2. [[CHDHDFAH]] + + 2. [[CHDHDFAH]] ++ Use the `imqusermgr` Message Queue utility to change the password of the `admin` user. - 3. [[CHDCJEFG]] + + 3. [[CHDCJEFG]] ++ Edit the configuration of the JMS host, changing the password of the `admin` user to the new password. - 4. [[CHDFJECE]] + - Restart the GlassFish instance that the broker is servicing. + + 4. [[CHDFJECE]] ++ + Restart the GlassFish instance that the broker is servicing. ++ When changing the password for the brokers in a broker cluster, first perform steps link:#CHDDHDIE[1] and link:#CHDHDFAH[2] on each broker. Then, perform step link:#CHDCJEFG[3]. Finally, perform @@ -1066,7 +1061,8 @@ Message Queue broker is running. Administrations Server (DAS), the log is available at domain-dir`/logs/server.log`; for other GlassFish instances, the log is available at -as-install`/nodes/`node-name`/`instance-name`/logs/server.log`. + +as-install`/nodes/`node-name`/`instance-name`/logs/server.log`. ++ If the log file indicates that a Message Queue broker acting as a Remote JMS host did not respond to a message, stop the broker and then restart it. @@ -1080,8 +1076,9 @@ first, then GlassFish Server instances. * If all Message Queue brokers are down, it can take up to 30 minutes for GlassFish Server to go down or up when you are using the default values in JMS. You can change the default values for this timeout. For -example: + -[source,oac_no_warn] +example: ++ +[source] ---- asadmin set domain1.jms-service.reconnect-interval-in-seconds=5 ---- @@ -1130,7 +1127,8 @@ repository. ** If javabean is specified then the resource adapter will obtain JMS connection factories and destinations by instantiating the appropriate -classes directly. + +classes directly. ++ Which option is specified determines which other properties need to be set. @@ -1144,18 +1142,23 @@ available to GlassFish Server. For some JMS providers, client libraries might also include native libraries. In such cases, these native libraries must be made available to any GlassFish Server JVMs. -1. Download the `genericra.rar` archive. -2. Deploy GenericJMSRA the same way you would deploy a connector -module. + +1. Download the `genericra.rar` archive. +2. Deploy GenericJMSRA the same way you would deploy a connector +module. ++ See "link:../application-deployment-guide/deploying-applications.html#GSDPG00069[Deploying a Connector Module]" in GlassFish Server Open Source Edition Application Deployment Guide. -3. Configure the resource adapter's properties. + +3. Configure the resource adapter's properties. ++ See link:#gbtvu[GenericJMSRA Configuration Properties]. -4. Create a connector connection pool. + +4. Create a connector connection pool. ++ See link:connectors.html#gioce[To Create a Connector Connection Pool]. -5. Create a connector resource. + +5. Create a connector resource. ++ See link:connectors.html#giogt[To Create a Connector Resource]. -6. Create an administered object resource. + +6. Create an administered object resource. ++ See link:connectors.html#giolr[To Create an Administered Object]. [[gbtvu]][[GSADG00674]][[genericjmsra-configuration-properties]] @@ -1502,7 +1505,7 @@ Administration Console or the `asadmin` command. If you use theAdministration Console then you need deploy the GenericJMSRA resource archive first. Here's an example using `asadmin`: -[source,oac_no_warn] +[source] ---- asadmin create-resource-adapter-config --host localhost --port 4848 --property SupportsXA=false:DeliveryType=Synchronous:ProviderIntegrationMode @@ -1529,7 +1532,7 @@ In this example, the following properties are configured: |`DeliveryType` |`Synchronous` |`ProviderIntegrationMode` |`jndi` |`JndiProperties` a| -[source,oac_no_warn] +[source] ---- java.naming.factory.initial =weblogic.jndi.WLInitialContextFactory,java.naming.provider.url @@ -1549,13 +1552,11 @@ properties needed for connecting to WebLogic JNDI. [NOTE] -======================================================================= - +==== When using `asadmin` you need to escape each `=` and any `:` characters by prepending a backward slash `\`. The escape sequence is not necessary if the configuration is performed through the Administration Console. - -======================================================================= +==== For a description of all the resource adapter properties that are @@ -1567,11 +1568,12 @@ of GenericJMSRA Properties for WebLogic JMS]. Deploy the GenericJMSRA Resource Archive ++++++++++++++++++++++++++++++++++++++++ -1. Download the GenericJMSRA resource archive (genericra.rar). -2. Deploy the resource adapter. You can do this using either the +1. Download the GenericJMSRA resource archive (genericra.rar). +2. Deploy the resource adapter. You can do this using either the Administration Console or the `asadmin` deploy command. Here's an -example using the `asadmin` deploy command: + -[source,oac_no_warn] +example using the `asadmin` deploy command: ++ +[source] ---- $ asadmin deploy --user admin --password adminadmin @@ -1592,8 +1594,9 @@ deployment descriptor files: `ejb-jar.xml` and the GlassFish Server from WebLogic JMS, you would configure these deployment descriptor files as follows: -1. Configure the ejb-jar.xml deployment descriptor: + -[source,oac_no_warn] +1. Configure the ejb-jar.xml deployment descriptor: ++ +[source,xml] ---- @@ -1617,19 +1620,17 @@ as follows: ---- -:: - ++ [NOTE] -======================================================================= - +==== If container-managed transactions are configured, then the transactional attribute must be set to `NotSupported`. For more information, see link:#gkkvz[Limitations When Using GenericJMSRA with WebLogic JMS]. +==== -======================================================================= - -2. Configure the glassfish-ejb-jar.xml deployment descriptor: + -[source,oac_no_warn] +2. Configure the glassfish-ejb-jar.xml deployment descriptor: ++ +[source,xml] ---- @@ -1660,12 +1661,14 @@ link:#gkkvz[Limitations When Using GenericJMSRA with WebLogic JMS]. ---- -where: + +where: ++ The `genericra` element is used to specify the resource adapter and resource adapter configurations that was deployed in the link:#gkmee[Create a Resource Adapter Configuration for GenericJMSRA to Work With WebLogic JMS] instructions. -It is recommended you stick to `genericra` as is used here. + +It is recommended you stick to `genericra` as is used here. ++ The `activation-config` element in `glassfish-ejb-jar.xml` is the one which defines how and where the MDB receives messages, as follows: * The `ConnectionFactoryJndiName` property must be set to the JNDI name @@ -1676,12 +1679,14 @@ the example above with the JNDI name used in your environment. destination (the queue or topic from which messages will be consumed) in the WebLogic JNDI store. Therefore, replace `jms/WLInboundQueue` in the example above with the JNDI name used in your environment. + + For a description of all the ActivationSpec properties that are relevant for WebLogic JMS, see the link:#gktfi[Configuration Reference of GenericJMSRA Properties for WebLogic JMS]. + + Make sure to use the appropriate WebLogic administration tools, such as -the WebLogic Administration Console or the WebLogic Scripting Tool -(WLST). For more information, see +the WebLogic Administration Console or the WebLogic Scripting Tool (WLST). +For more information, see "http://www.oracle.com/pls/as1111/lookup?id=WLACH01853[Configure Messaging]" in WebLogic Server Administration Console Online Help and http://www.oracle.com/pls/as1111/lookup?id=WLSTC112[WebLogic Server WLST @@ -1703,8 +1708,7 @@ using a JNDI lookup. [NOTE] -======================================================================= - +==== If you want configure connections and destination resources using the Administration Console, this is explained in the Administration Console online help. When using Administration Console, follow the instructions @@ -1714,18 +1718,19 @@ Destination Resources. For more information about using `asadmin` to create these resources, see link:connectors.html#gioce[To Create a Connector Connection Pool] and link:connectors.html#giogt[To Create a Connector Resource]. - -======================================================================= +==== -1. Looking up the connection factory and destination + +1. Looking up the connection factory and destination ++ The following code looks up a connection factory with the JNDI name -`jms/QCFactory` and a queue with the name`jms/outboundQueue` from the -GlassFish Server JNDI store: + -[source,oac_no_warn] +`jms/QCFactory` and a queue with the name `jms/outboundQueue` from the +GlassFish Server JNDI store: ++ +[source,java] ---- Context initialContect = new InitialContext(); - QueueConnectionFactory queueConnectionFactory = (QueueConnectionFactory) + QueueConnectionFactory queueConnectionFactory = (QueueConnectionFactory) jndiContext.lookup("java:comp/env/jms/MyQCFactory"); Queue queue = (Queue) jndiContext.lookup("java:comp/env/jms/outboundQueue"); ---- @@ -1735,12 +1740,14 @@ you want to use in the WebLogic JMS JNDI store, you need to create a corresponding connection factory or destination in the GlassFish Server JNDI store and configure the GlassFish Server object to point to the corresponding WebLogic JMS object. -2. Declaring the connection factory and destination + +2. Declaring the connection factory and destination ++ In accordance with standard Java EE requirements, these resources need to be declared in the deployment descriptor for the MDB, EJB or other component. For example, for a session bean, configure the `ejb-jar.xml` -with `` elements, as follows: + -[source,oac_no_warn] +with `` elements, as follows: ++ +[source,xml] ---- @@ -1755,21 +1762,23 @@ with `` elements, as follows: + jakarta.jms.Queue ---- -3. Create a Connector Connection Pool and Connector Resource by -entering the following `asadmin` commands, both all in one line: + +3. Create a Connector Connection Pool and Connector Resource by +entering the following `asadmin` commands, both all in one line: ++ In order to configure a JMS Connection Factory using GenericJMSRA, a Connector connection pool and resource need to be created in GlassFish Server using names that map to the corresponding connection factory in -the WebLogic JNDI store. + -[source,oac_no_warn] +the WebLogic JNDI store. ++ +[source] ---- asadmin create-connector-connection-pool --host localhost --port 4848 - --raname genericra --connectiondefinition jakarta.jms.QueueConnectionFactory + --raname genericra --connectiondefinition jakarta.jms.QueueConnectionFactory --target server --transactionsupport LocalTransaction --property ConnectionFactoryJndiName=jms/WLOutboundQueueFactory qcpool -asadmin create-connector-resource --host localhost --port 4848 +asadmin create-connector-resource --host localhost --port 4848 --poolname qcpool --target server jms/QCFactory ---- These `asadmin` commands together creates a connection factory in @@ -1786,8 +1795,9 @@ link:#gkkvz[Limitations When Using GenericJMSRA with WebLogic JMS]. * The connection pool is configured with the properties specified using the `properties` argument; multiple properties are configured as a colon-separated list of name-value pairs. Only one property is -configured in this example, as follows: + -[source,oac_no_warn] +configured in this example, as follows: ++ +[source] ---- ConnectionFactoryJndiName=jms/WLOutboundQueueFactory ---- @@ -1798,13 +1808,14 @@ with the JNDI name used in your environment. * For a description of the `ManagedConnectionFactory` properties that are relevant for WebLogic JMS, see the link:#gktfi[Configuration Reference of GenericJMSRA Properties for WebLogic JMS]. -4. Create a destination object that refers to a corresponding WebLogic +4. Create a destination object that refers to a corresponding WebLogic JMS destination by entering the following `asadmin` command, all in one -line: + -[source,oac_no_warn] +line: ++ +[source] ---- -asadmin create-admin-object --host localhost --port 4848 --target server - --restype jakarta.jms.Queue --property DestinationJndiName=jms/WLOutboundQueue +asadmin create-admin-object --host localhost --port 4848 --target server + --restype jakarta.jms.Queue --property DestinationJndiName=jms/WLOutboundQueue --raname genericra jms/outboundQueue ---- This `asadmin` command creates a destination in GlassFish Server. @@ -1813,8 +1824,9 @@ resource adapter `genericra`, and is of type `jakarta.jms.Queue`. * The destination is configured with the properties specified using the `properties` argument; multiple properties are configured as a colon-separated list of name-value pairs. Only one property is -configured in this example, as follows: + -[source,oac_no_warn] +configured in this example, as follows: ++ +[source] ---- DestinationJndiName=jms/WLOutboundQueue ---- @@ -1943,7 +1955,8 @@ MDBs to process messages from the queue. will be used irrespective of the configured pool size. This means that a pool of multiple MDBs cannot be used to share the load of processing messages, which may reduce the rate at which messages can be received -and processed. + +and processed. ++ This restriction is a consequence of the semantics of synchronously consuming messages from topics in JMS: In the case of non-durable topic subscriptions, each consumer receives a copy of all the messages on the @@ -1993,15 +2006,12 @@ in WebLogic's JNDI store. Set to `jndi` for WebLogic JMS. |`JndiProperties` a| -[source,oac_no_warn] +[source] ---- -java.naming.factory.initial -=weblogic.jndi.WLInitialContextFactory, -java.naming.provider.url -=t3://localhost:7001,java.naming.factory.url.pkgs -=weblogic.corba.client.naming -(replace localhost:7001 with -the host:port of WebLogic Server) +java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory, +java.naming.provider.url=t3://localhost:7001, +java.naming.factory.url.pkgs=weblogic.corba.client.naming +(replace localhost:7001 with the host:port of WebLogic Server) ---- |JNDI properties for connect to WebLogic JNDI, specified as @@ -2092,7 +2102,7 @@ used. |Only used for topics. Specifies whether the subscription is durable or non-durable. -|`SubscriptionName` | + |None |Only used for topics when +|`SubscriptionName` | |None |Only used for topics when `SubscriptionDurability` is `Durable`. Specifies the name of the durable subscription. @@ -2165,8 +2175,9 @@ application. ** Use a text editor to modify the `server.policy` file in the `${appserver-install-dir}/domains/domain1/config/`directory by adding -the following line to the default grant block: + -[source,oac_no_warn] +the following line to the default grant block: ++ +[source] ---- permission java.util.logging.LoggingPermission "control"; permission java.util.PropertyPermission "*", "read,write"; @@ -2175,8 +2186,9 @@ permission java.util.PropertyPermission "*", "read,write"; ** If you use an application client in your application, edit the client's `client.policy` file in the `${appserver-install-dir}/lib/appclient/` directory by adding the -following permission: + -[source,oac_no_warn] +following permission: ++ +[source] ---- permission javax.security.auth.PrivateCredentialPermission "javax.resource.spi.security.PasswordCredential * \"*\"","read"; @@ -2185,8 +2197,9 @@ permission javax.security.auth.PrivateCredentialPermission necessary JAR files to the as-install`/lib` directory: ** For WebSphere MQ 6.0, copy these JAR files to the as-install`/lib` -directory: + -[source,oac_no_warn] +directory: ++ +[source] ---- /opt/mqm/java/lib/com.ibm.mq.jar /opt/mqm/java/lib/com.ibm.mq.jms.Nojndi.jar @@ -2203,8 +2216,9 @@ directory: + where `/opt/mqm` is the location of the WebSphere MQ 6.0 installation. ** For WebSphere MQ 7.0, copy these JAR files to the as-install`/lib` -directory: + -[source,oac_no_warn] +directory: ++ +[source] ---- /opt/mqm/java/lib/com.ibm.mq.jar, /opt/mqm/java/lib/com.ibm.mq.jms.Nojndi.jar, @@ -2222,8 +2236,9 @@ where `/opt/mqm` is the location of the WebSphere MQ 7.0 installation. * Set the `LD_LIBRARY_PATH` environment variable to the `java/lib` directory, and then restart GlassFish Server. For example, in a UNIX—based system, with WebSphere MQ installed under `/opt/mqm`, you -would enter: + -[source,oac_no_warn] +would enter: ++ +[source] ---- $ export LD_LIBRARY_PATH=/opt/mqm/java/lib ---- @@ -2252,96 +2267,107 @@ image:img/websphere-mq.png[ example configuration."] -1. Switch to the `mqm` user: + +1. Switch to the `mqm` user: + `$ su mqm` -2. For Linux, set the following kernel version: + + +2. For Linux, set the following kernel version: + `$ export LD_ASSUME_KERNEL=2.2.5` -3. Create a new MQ queue manager named "QM1": + + +3. Create a new MQ queue manager named "QM1": + `$ crtmqm QM1` -4. Start the new MQ queue manager. + -In the image above, `QM1` is associated with the IBM WebSphere MQ -broker. + + +4. Start the new MQ queue manager. + +In the image above, `QM1` is associated with the IBM WebSphere MQ broker. + `$ strmqm QM1` -5. Start the MQ listener: + + +5. Start the MQ listener: + `$ runmqlsr -t tcp -m QM1 -p 1414 &` -6. Modify the default JMSAdmin console configuration as follows: -1. Edit the JMSAdmin script in the `/opt/mqm/java/bin` directory to -change the JVM to a location of a valid JVM your system. -2. Set the relevant environment variable required for JMSAdmin by -sourcing the `setjmsenv` script located in the `/opt/mqm/java/bin` -directory. + -[source,oac_no_warn] + +6. Modify the default JMSAdmin console configuration as follows: +[arabic] +.. Edit the JMSAdmin script in the `/opt/mqm/java/bin` directory to + change the JVM to a location of a valid JVM your system. +.. Set the relevant environment variable required for JMSAdmin by + sourcing the `setjmsenv` script located in the `/opt/mqm/java/bin` directory. ++ +[source] ---- $ cd /opt/mqm/java/bin $ source setjmsenv ---- where `/opt/mqm` is the location of the WebSphere MQ installation. -3. Change the JMSAdmin.config file to indicate the Initial Context -Factory you will be using by setting the following name-value pairs and -commenting out the rest: + -[source,oac_no_warn] +.. Change the JMSAdmin.config file to indicate the Initial Context Factory + you will be using by setting the following name-value pairs and + commenting out the rest: ++ +[source] ---- INITIAL_CONTEXT_FACTORY=com.sun.jndi.fscontext.RefFSContextFactory - PROVIDER_URL=file:/opt/tmp +PROVIDER_URL=file:/opt/tmp ---- -7. Create WebSphere MQ queues using the runmqsc console and -MQJMS_PSQ.mqsc script. + + +7. Create WebSphere MQ queues using the runmqsc console and MQJMS_PSQ.mqsc script. + `$ runmqsc QM1 < MQJMS_PSQ.mqsc` -8. Create user defined physical queue for your application using + +8. Create user defined physical queue for your application using runmqsc console and an appropriate physical queue name. An example of how this could be done is shown below. + -In the image above, `ORANGE.LOCAL.QUEUE` is associated with `QM1`. + -[source,oac_no_warn] +In the image above, `ORANGE.LOCAL.QUEUE` is associated with `QM1`. ++ +[source] ---- $ runmqsc QM1 > DEFINE QLOCAL(ORANGE.LOCAL.QUEUE) > end ---- -9. Start the WebSphere MQ Broker: + + +9. Start the WebSphere MQ Broker: + `$ strmqbrk -m QM1` + 10. In the WebSphere MQ JMSAdmin console, use the following commands to create the connection factories, XA connection factories, and destinations for your application, as shown in the following sample, which lists each of the various JMS administered objects. + In the image above, `QCF` (for `QM1`) and `TQueue` (associated with -`ORANGE.LOCAL.QUEUE`) are defined in the `FileSystem Naming Context`. + -[source,oac_no_warn] +`ORANGE.LOCAL.QUEUE`) are defined in the `FileSystem Naming Context`. ++ +[source] ---- $ ./JMSAdmin - - InitCtx>def qcf + + InitCtx>def qcf hostname port(1414) channel(SYSTEM.DEF.SVRCONN) transport(CLIENT) qmanager - + For example: - def qcf(QCF) hostname(localhost) port(1414) channel(SYSTEM.DEF.SVRCONN) + def qcf(QCF) hostname(localhost) port(1414) channel(SYSTEM.DEF.SVRCONN) transport(CLIENT) qmanager(QM1) - - InitCtx%def xaqcf + + InitCtx%def xaqcf hostname port(1414) channel(SYSTEM.DEF.SVRCONN) transport(CLIENT) qmanager - + For example: - def xaqcf(XAQCF) hostname(localhost) port(1414) channel(SYSTEM.DEF.SVRCONN) + def xaqcf(XAQCF) hostname(localhost) port(1414) channel(SYSTEM.DEF.SVRCONN) transport(CLIENT) qmanager(QM1) - - InitCtx%def q queue + + InitCtx%def q queue qmanager(name of queue manager defined ) - + For example: def q(TQueue) queue(ORANGE.LOCAL.QUEUE) qmanager(QM1) - - InitCtx%def tcf + + InitCtx%def tcf qmanager(name of queue manager defined ) - + For example: def tcf(TCF) qmanager(QM1) - - InitCtx%def xatcf + + InitCtx%def xatcf qmanager(name of queue manager defined ) - + For example: def xatcf(XATCF) qmanager(QM1) - + InitCtx%def t topic - + For example: def t(TTopic) topic(topic) ---- @@ -2356,7 +2382,7 @@ Administration Console or the `asadmin` command. Use the following `asadmin` command to create a resource adapter configuration for `genericra` to configure it to work with WebSphere MQ. -[source,oac_no_warn] +[source] ---- asadmin> create-resource-adapter-config --user --password @@ -2371,16 +2397,14 @@ Administration Console or the `asadmin` command. Use the following [NOTE] -======================================================================= - +==== When using `asadmin` you need to escape each `=` and any `:` characters by prepending a backward slash `\`. The escape sequence is not necessary if the configuration is performed through the Administration Console. Also , ensure that the provider URL is configured correctly depending on the platform. For example, on Windows systems it should be `file:/C:/opt/tmp` and on UNIX—based systems it is `file://opt/tmp`. - -======================================================================= +==== This creates a resource adapter configuration with the name `genericra`, @@ -2394,61 +2418,62 @@ In this example, the following properties are configured: [NOTE] -======================================================================= - +==== The tables in this section describe the GenericJMSRA properties that are relevant only when integrating with WebSphere MQ. For a complete list of properties, see the comprehensive table in link:#gbtvu[GenericJMSRA Configuration Properties]. - -======================================================================= +==== -[width="100%",cols="29%,43%,28%",options="header",] -|======================================================================= +[width="100%",cols="25%,45%,30%",options="header",] +|=== |Property Name |Required Value |Description -|`SupportsXA` |`true` |Set the supports distributed transactions -attribute to `true`. The level of transactional support the adapter -provides -- none, local, or XA -- depends on the capabilities of the +|`SupportsXA` +|`true` +|Set the supports distributed transactions attribute to `true`. +The level of transactional support the adapter provides +-- none, local, or XA -- depends on the capabilities of the Enterprise Information System (EIS) being adapted. If an adapter supports XA transactions and this attribute is XA, the application can use distributed transactions to coordinate the EIS resource with JDBC and JMS resources. -|`ProviderIntegrationMode` |`jndi` |Specifies that connection factories +|`ProviderIntegrationMode` +|`jndi` +|Specifies that connection factories and destinations in GlassFish's JNDI store are configured to refer to connection factories and destinations in WebSphere MQ's JNDI store. -|`JndiProperties` a| -[source,oac_no_warn] +|`JndiProperties` +a| +[source] ---- -JndiProperties= -java.naming.factory.url.pkgs\\ -=com.ibm.mq.jms.naming,java.naming. -factory.initial\\=com.sun.jndi.fscontext. -RefFSContextFactory,java.naming. -provider.url\\ -=file\\:\\/\\/opt\\/tmp: -LogLevel=finest genericra +JndiProperties=java.naming.factory.url.pkgs\\=com.ibm.mq.jms.naming, +java.naming.factory.initial\\=com.sun.jndi.fscontext.RefFSContextFactory, +java.naming.provider.url\\=file\\:\\/\\/opt\\/tmp:LogLevel=finest genericra ---- - - |JNDI properties for connecting to WebSphere MQ's JNDI, specified as +|JNDI properties for connecting to WebSphere MQ's JNDI, specified as comma-separated list of name=value pairs without spaces. -|`UserName` |`Name of the WebSphere MQ user` a| +|`UserName` +|`Name of the WebSphere MQ user` +a| User name to connect to WebSphere MQ. - The user name can be overridden in `ActivationSpec` and `ManagedConnection`. If no user name is specified anonymous connections will be used, if permitted. -|`Password` |`Password for the WebSphere MQ user` a| +|`Password` +|`Password for the WebSphere MQ user` +a| Password to connect to WebSphere MQ. - The password can be overridden in `ActivationSpec` and `ManagedConnection`. -|`RMIPolicy` |`OnePerPhysicalConnection` a| +|`RMIPolicy` +|`OnePerPhysicalConnection` +a| Some XAResource implementations, such as WebSphere MQ, rely on a Resource Manager per Physical Connection, and this causes issues when there is inbound and outbound communication to the same queue manager in @@ -2461,20 +2486,19 @@ the XAResources use the same physical connection, before delegating to the wrapped objects. Therefore, ensure that this attribute is set to `OnePerPhysicalConnection` if the application uses XA. -|`LogLevel` |`Desired log level of JDK logger` |Used to specify the -level of logging. -|======================================================================= +|`LogLevel` +|`Desired log level of JDK logger` +|Used to specify the level of logging. +|=== [NOTE] -======================================================================= - +==== You must use the values for `SupportsXA`, `RMPolicy` and `ProviderIntegrationMode` as the required values that are used in this table. - -======================================================================= +==== [[gksnh]][[GSADG00685]][[deploy-the-genericjmsra-archive]] @@ -2501,8 +2525,7 @@ GlassFish Server. [NOTE] -======================================================================= - +==== If you want configure connections and destination resources using the Administration Console, this is explained in the Administration Console online help. When using Administration Console, following the, @@ -2512,8 +2535,7 @@ Pool and Destination Resources. For more information about using `asadmin` to create these resources, see link:connectors.html#gioce[To Create a Connector Connection Pool] and link:connectors.html#giogt[To Create a Connector Resource]. - -======================================================================= +==== [[gksro]][[GSADG00502]][[creating-connections-and-destinations]] @@ -2528,55 +2550,65 @@ destination name in these steps map to the example WebSphere MQ configuration in link:#gksli[Configure the WebSphere MQ Administered Objects]. -1. Create connection pools that point to the connection pools in -WebSphere MQ. + +1. Create connection pools that point to the connection pools in +WebSphere MQ. ++ The following `asadmin` command creates a Connection Pool called -`mypool` and points to the `XAQCF` created in WebSphere MQ: + -[source,oac_no_warn] +`mypool` and points to the `XAQCF` created in WebSphere MQ: ++ +[source] ---- asadmin create-connector-connection-pool -- raname genericra connectiondefinition - jakarta.jms.QueueConnectionFactory --transactionsupport XATransaction + jakarta.jms.QueueConnectionFactory --transactionsupport XATransaction --property ConnectionFactoryJndiName=QCF mypool ---- The following `asadmin` command creates a Connection Pool called -`mypool2` and points to the `XATCF` created in WebSphere MQ: + -[source,oac_no_warn] +`mypool2` and points to the `XATCF` created in WebSphere MQ: ++ +[source] ---- - asadmin create-connector-connection-pool - -- raname genericra connectiondefinition jakarta.jms.TopicConnectionFactory + asadmin create-connector-connection-pool + -- raname genericra connectiondefinition jakarta.jms.TopicConnectionFactory --transactionsupport XATransaction --property ConnectionFactoryJndiName=XATCF mypool2 ---- -2. Create the connector resources. + +2. Create the connector resources. ++ The following `asadmin` command creates a connector resource named -`jms/MyQCF` and binds this resource to JNDI for applications to use: + -[source,oac_no_warn] +`jms/MyQCF` and binds this resource to JNDI for applications to use: ++ +[source] ---- asadmin create-connector-resource --poolname mypool jms/MyQCF ---- The following `asadmin` command creates a connector resource named -`jms/MyTCF` and binds this resource to JNDI for applications to use: + -[source,oac_no_warn] +`jms/MyTCF` and binds this resource to JNDI for applications to use: ++ +[source] ---- asadmin create-connector-resource --poolname mypool2 jms/MyTCF ---- -3. Create the JMS destination resources as administered objects. + +3. Create the JMS destination resources as administered objects. ++ In the image above, `jms/MyQueue` (pointing to `GenericJMSRA` and -`TQueue`) is created in GlassFish Server. + +`TQueue`) is created in GlassFish Server. ++ The following `asadmin` command creates a `jakarta.jms.Queue` administered object and binds it to the GlassFish Server JNDI tree at `jms/MyQueue` -and points to the `jms/TQueue` created in WebSphere MQ. + -[source,oac_no_warn] +and points to the `jms/TQueue` created in WebSphere MQ. ++ +[source] ---- - asadmin create-admin-object --raname genericra --restype jakarta.jms.Queue + asadmin create-admin-object --raname genericra --restype jakarta.jms.Queue --property DestinationJndiName=TQueue jms/MyQueue ---- The following `asadmin` command creates a `jakarta.jms.Topic` administered object and binds it to the GlassFish Server JNDI tree at `jms/MyTopic` -and points to the `jms/TTopic` created in WebSphere MQ. + -[source,oac_no_warn] +and points to the `jms/TTopic` created in WebSphere MQ. ++ +[source] ---- - asadmin create-admin-object --raname genericra --restype jakarta.jms.Topic + asadmin create-admin-object --raname genericra --restype jakarta.jms.Topic --property DestinationJndiName=TTopic jms/MyTopic ---- @@ -2594,7 +2626,7 @@ Bean that listens to a destination called `TQueue` in WebSphere MQ, and publishes back reply messages to a destination resource named `jms/replyQueue` in GlassFish Server, as shown below. -[source,oac_no_warn] +[source,xml] ---- @@ -2617,7 +2649,7 @@ publishes back reply messages to a destination resource named jms/replyQueue jms/replyQueue - + @@ -2670,19 +2702,18 @@ The business logic encoded in Message Driven Bean could then lookup the configured `QueueConnectionFactory/Destination` resource to create a connection as shown below. -[source,oac_no_warn] +[source,java] ---- Context context = null; ConnectionFactory connectionFactory = null; - logger>info("In PublisherBean>ejbCreate()"); + logger.info("In PublisherBean>ejbCreate()"); try { context = new InitialContext(); - queue = (javax>jms>Queue) context>lookup ("java:comp/env/jms/replyQueue"); + queue = (javax.jms.Queue) context.lookup ("java:comp/env/jms/replyQueue"); connectionFactory = (ConnectionFactory) context>lookup("java:comp/env/jms/MyQueueConnectionFactory"); connection = connectionFactory>createConnection(); } catch (Throwable t) { - logger>severe("PublisherBean>ejbCreate:" + "Exception: " + - t>toString()); + logger.severe("PublisherBean>ejbCreate:" + "Exception: " + t.toString()); } ---- diff --git a/docs/administration-guide/src/main/jbake/content/jndi.adoc b/docs/administration-guide/src/main/jbake/content/jndi.adoc index 0495f1d68fb7..5c5af33b9504 100644 --- a/docs/administration-guide/src/main/jbake/content/jndi.adoc +++ b/docs/administration-guide/src/main/jbake/content/jndi.adoc @@ -4,6 +4,7 @@ title=Administering the Java Naming and Directory Interface (JNDI) Service next=transactions.html prev=jms.html ~~~~~~ + Administering the Java Naming and Directory Interface (JNDI) Service ==================================================================== @@ -189,23 +190,22 @@ To Create a Custom JNDI Resource Use the `create-custom-resource` subcommand in remote mode to create a custom resource. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Create a custom resource by using the -link:../reference-manual/create-custom-resource.html#GSRFM00022[`create-custom-resource`] subcommand. + +1. Ensure that the server is running. Remote subcommands require a running server. +2. Create a custom resource by using the +link:../reference-manual/create-custom-resource.html#GSRFM00022[`create-custom-resource`] subcommand. ++ Information on properties for the subcommand is contained in this help page. -3. Restart GlassFish Server. + +3. Restart GlassFish Server. ++ See link:domains.html#ginqj[To Restart a Domain]. [[GSADG00284]][[gioyi]] - - Example 18-1 Creating a Custom Resource This example creates a custom resource named `sample-custom-resource`. -[source,oac_no_warn] +[source] ---- asadmin> create-custom-resource --restype topic --factoryclass com.imq.topic sample_custom_resource @@ -227,19 +227,16 @@ To List Custom JNDI Resources Use the `list-custom-resources` subcommand in remote mode to list the existing custom resources. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the custom resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the custom resources by using the link:../reference-manual/list-custom-resources.html#GSRFM00162[`list-custom-resources`] subcommand. [[GSADG00285]][[gioyr]] - - Example 18-2 Listing Custom Resources This example lists the existing custom resources. -[source,oac_no_warn] +[source] ---- asadmin> list-custom-resources sample_custom_resource01 @@ -259,19 +256,17 @@ typing `asadmin help list-custom-resources` at the command line. To Update a Custom JNDI Resource ++++++++++++++++++++++++++++++++ -1. List the custom resources by using the +1. List the custom resources by using the link:../reference-manual/list-custom-resources.html#GSRFM00162[`list-custom-resources`] subcommand. -2. Use the link:../reference-manual/set.html#GSRFM00226[`set`] subcommand to modify a custom JNDI +2. Use the link:../reference-manual/set.html#GSRFM00226[`set`] subcommand to modify a custom JNDI resource. [[GSADG00286]][[giwkg]] - - Example 18-3 Updating a Custom JNDI Resource This example modifies a custom resource. -[source,oac_no_warn] +[source] ---- asadmin> set server.resources.custom-resource.custom /my-custom-resource.property.value=2010server.resources.custom-resource.custom @@ -286,21 +281,18 @@ To Delete a Custom JNDI Resource Use the `delete-custom-resource` subcommand in remote mode to delete a custom resource. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the custom resources by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the custom resources by using the link:../reference-manual/list-custom-resources.html#GSRFM00162[`list-custom-resources`] subcommand. -3. Delete a custom resource by using the +3. Delete a custom resource by using the link:../reference-manual/delete-custom-resource.html#GSRFM00074[`delete-custom-resource`] subcommand. [[GSADG00287]][[gioxh]] - - Example 18-4 Deleting a Custom Resource This example deletes a custom resource named `sample-custom-resource`. -[source,oac_no_warn] +[source] ---- asadmin> delete-custom-resource sample_custom_resource Command delete-custom-resource executed successfully. @@ -349,23 +341,22 @@ Before You Begin The external JNDI factory must implement the `javax.naming.spi.InitialContextFactory` interface. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Register an external JNDI resource by using the -link:../reference-manual/create-jndi-resource.html#GSRFM00041[`create-jndi-resource`] subcommand. + +1. Ensure that the server is running. Remote subcommands require a running server. +2. Register an external JNDI resource by using the +link:../reference-manual/create-jndi-resource.html#GSRFM00041[`create-jndi-resource`] subcommand. ++ Information on properties for the subcommand is contained in this help page. -3. Restart GlassFish Server. + +3. Restart GlassFish Server. ++ See link:domains.html#ginqj[To Restart a Domain]. [[GSADG00288]][[giwcx]] - - Example 18-5 Registering an External JNDI Resource In This example `sample_jndi_resource` is registered. -[source,oac_no_warn] +[source] ---- asadmin> create-jndi-resource --jndilookupname sample_jndi --restype queue --factoryclass sampleClass --description "this is a sample jndi @@ -388,19 +379,16 @@ To List External JNDI Resources Use the `list-jndi-resources` subcommand in remote mode to list all existing JNDI resources. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the existing JNDI resources by using +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the existing JNDI resources by using theolink:GSRFM00179[`list-jndi-resources`] subcommand. [[GSADG00289]][[giwbe]] - - Example 18-6 Listing JNDI Resources This example lists the JNDI resources. -[source,oac_no_warn] +[source] ---- asadmin> list-jndi-resources jndi_resource1 @@ -425,19 +413,16 @@ Use the `list-jndi-entries` subcommand in remote mode to browse and list the entries in the JNDI tree. You can either list all entries, or you can specify the JNDI context or subcontext to list specific entries. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. List the JNDI entries for a configuration by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. List the JNDI entries for a configuration by using the link:../reference-manual/list-jndi-entries.html#GSRFM00178[`list-jndi-entries`] subcommand. [[GSADG00290]][[giwal]] - - Example 18-7 Listing JNDI Entries This example lists all the JNDI entries for the naming service. -[source,oac_no_warn] +[source] ---- asadmin> list-jndi-entries jndi_entry03 @@ -458,19 +443,17 @@ typing `asadmin help list-jndi-entries` at the command line. To Update an External JNDI Resource +++++++++++++++++++++++++++++++++++ -1. List the existing JNDI resources by using +1. List the existing JNDI resources by using theolink:GSRFM00179[`list-jndi-resources`] subcommand. -2. Use the link:../reference-manual/set.html#GSRFM00226[`set`] subcommand to modify an external +2. Use the link:../reference-manual/set.html#GSRFM00226[`set`] subcommand to modify an external JNDI resource. [[GSADG00291]][[giwoa]] - - Example 18-8 Updating an External JNDI Resource This example modifies an external resource. -[source,oac_no_warn] +[source] ---- asadmin> set server.resources.external-jndi-resource.my-jndi-resource. jndi-lookup-name=bar server.resources.external-jndi-resource.my-jndi-resource.jndi-lookup-name=bar @@ -484,19 +467,16 @@ To Delete an External JNDI Resource Use the `delete-jndi-resource` subcommand in remote mode to remove a JNDI resource. -1. Ensure that the server is running. + -Remote subcommands require a running server. -2. Remove an external JNDI entry by using the +1. Ensure that the server is running. Remote subcommands require a running server. +2. Remove an external JNDI entry by using the link:../reference-manual/delete-jndi-resource.html#GSRFM00093[`delete-jndi-resource`] subcommand. [[GSADG00292]][[giwby]] - - Example 18-9 Deleting an External JNDI Resource This example deletes an external JNDI resource: -[source,oac_no_warn] +[source] ---- asadmin> delete-jndi-resource jndi_resource2 Command delete-jndi-resource executed successfully. @@ -514,7 +494,7 @@ typing `asadmin help delete-jndi-resource` at the command line. Example of Using an External JNDI Resource ++++++++++++++++++++++++++++++++++++++++++ -[source,oac_no_warn] +[source,xml] ----