| Oracle GlassFish Server Administration Guide Release 3.1.2 Part Number E24928-01 |
|
|
View PDF |
| Oracle GlassFish Server Administration Guide Release 3.1.2 Part Number E24928-01 |
|
|
View PDF |
This chapter provides information and procedures for administering connections to enterprise information system (EconIS) data in the Oracle GlassFish Server 3.1.2 environment by using the asadmin command-line 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:
Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.
For information about database connectivity, see Administering Database Connectivity.
Enterprise information system (EIS) refers to any system that holds the data of an organization. It can be a mainframe, a messaging system, a database system, or an application. Connection resources are used by applications and modules to access EIS software.)
The key elements of EIS connectivity are the following:
Connector Module. A connector module, also called a resource adapter, is a Java EE component that enables applications to interact with EIS software. A connector module is used by GlassFish Server to implement Java Message Service (JMS). Like other Java EE modules, a connector module is installed when it is deployed. For instructions on creating a connector module, see "Developing Connectors" in Oracle GlassFish Server Application Development Guide.
Connector Connection Pool. A connector connection pool is a group of reusable connections for a particular EIS. A connector connection pool is created when you specify the connector module that is associated with the pool. For administration procedures, see Administering Connector Connection Pools.
Connector Resource. A connector resource is a program object that provides an application with a connection to an EIS. A connector resource is created when you specify its JNDI name and its associated connection pool. The JNDI name of a connector resource for an EIS is usually in the java:comp/env/eis-specific subcontext. For administration procedures, see Administering Connector Resources.
Connector Module Configuration. A connector module configuration is the information that resides in the domain configuration file (domain.xml) for the particular connector module (resource adapter). For administration procedures, see Administering the Resource Adapter Configuration.
Connector Security Map. A connector security map associates the caller identity of the application (principal or user group) to a suitable EIS principal or group. For administration procedures, see Administering Connector Security Maps.
Connector Work Security Map. A connector work security map associates the caller identity of the work submitted by the connector module (resource adapter) EIS principal or EIS user group to a suitable principal or user group in the GlassFish Server security domain. For administration procedures, see Administering Connector Work Security Maps.
Administered Object. An administered object provides specialized functionality for an application, such as providing access to a parser that is specific to the connector module and its associated EIS. For administration procedures, see Administering Administered Objects.
At runtime, the following sequence occurs when an application connects to an EIS:
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.
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.
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.
When the application is finished accessing the EIS, the application closes the connection and returns the connection to the connection pool.
After a connector module has been deployed, you are ready to create a connector connection pool for it.
The following topics are addressed here:
Use the create-connector-connection-pool subcommand in remote mode to create a connector connection pool for a deployed connector module. When you are building the connector connection pool, certain data specific to the EIS will be required. The value in the mandatory --connectiondefintion option provides the EIS info.
Multiple connector resources can specify a single connection pool.
Creating a connector connection pool is a dynamic event and does not require server restart. However, there are some parameters that do require server restart. See Configuration Changes That Require Restart.
Before creating the connector connection pool, the connector must be installed.
Ensure that the server is running.
Remote subcommands require a running server.
Create the connector connection pool by using the create-connector-connection-pool subcommand.
Information about properties for the subcommand is included in this help page.
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
You can verify that a connection pool is usable by using the ping-connection-pool subcommand.
For instructions, see To Contact (Ping) a Connection Pool.
Example 13-1 Creating a Connector Connection Pool
This example creates the new jms/qConnPool pool for the javax.jms.QueueConnectionFactory connector module.
asadmin> create-connector-connection-pool --steadypoolsize 20 --maxpoolsize 100 --poolresize 2 --maxwait 60000 --raname jmsra --connectiondefinition javax.jms.QueueConnectionFactory jms/qConnPool Command create-connector-connection-pool executed successfully
You can also view the full syntax and options of the subcommand by typing asadmin help create-connector-connection-pool at the command line.
Use the list-connector-connection-pools subcommand in remote mode to list the pools that have been created.
Ensure that the server is running.
Remote subcommands require a running server.
List the connector connection pools by using the list-connector-connection-pools subcommand.
Example 13-2 Listing Connector Connection Pools
This example lists the existing connector connection pools.
asadmin> list-connector-connection-pools
jms/qConnPool
Command list-connector-connection-pools executed successfully
You can also view the full syntax and options of the subcommand by typing asadmin help list-connector-connection-pools at the command line.
Use the ping-connection-pool or flush-connection-pool subcommands in remote mode to perform these tasks on a connection pools. See To Contact (Ping) a Connection Pool or To Reset (Flush) a Connection Pool for instructions.
Ensure that the server is running.
Remote subcommands require a running server.
Connect to or reset a connector connection pool by using the flush-connection-pool subcommand or the ping-connection-pool subcommand.
Use the get and set subcommands to view and change the values of the connector connection pool properties.
List the connector connection pools by using the list-connector-connection-pools subcommand.
View the properties of the connector connection pool by using the get subcommand.
For example:
asadmin> get domain.resources.connector-connection-pool.conectionpoolname.*
Set the property of the connector connection pool by using the set subcommand.
For example:
asadmin> set domain.resources.connector-connection-pool .conectionpoolname.validate-atmost-once-period-in-seconds=3
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Use the delete-connector-connection-pool subcommand in remote mode to remove a connector connection pool.
Ensure that the server is running.
Remote subcommands require a running server.
List the connector connection pools by using the list-connector-connection-pools subcommand.
If necessary, notify users that the connector connection pool is being deleted.
Delete the connector connection pool by using the delete-connector-connection-pool subcommand.
Example 13-3 Deleting a Connector Connection Pool
This example deletes the connection pool named jms/qConnPool.
asadmin> delete-connector-connection-pool --cascade=false jms/qConnPool
Command delete-connector-connection-pool executed successfully
You can also view the full syntax and options of the subcommand by typing asadmin help delete-connector-connection-pool at the command line.
A connector resource provides an application or module with the means of connecting to an EIS. Typically, you create a connector resource for each EIS that is accessed by the applications deployed in the domain.
The following topics are addressed here:
Use the create-connector-resource subcommand in remote mode to register a new connector resource with its JNDI name.
Creating a connector resource is a dynamic event and does not require server restart. However, there are some parameters that do require server restart. See Configuration Changes That Require Restart.
Before creating a connector resource, you must first create a connector connection pool. For instructions, see To Create a Connector Connection Pool.
Ensure that the server is running.
Remote subcommands require a running server.
Create the connector resource by using the create-connector-resource subcommand.
Information about properties for the subcommand is included in this help page.
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Example 13-4 Creating a Connector Resource
This example creates a new resource named jms/qConnFactory for the jms/qConnPool connection pool.
asadmin> create-connector-resource --poolname jms/qConnPool --description "creating sample connector resource" jms/qConnFactory Command create-connector-resource executed successfully
You can also view the full syntax and options of the subcommand by typing asadmin help create-connector-resource at the command line.
Use the list-connector-resources subcommand in remote mode to list the connector resources that have been created.
Ensure that the server is running.
Remote subcommands require a running server.
List the connector connection pools by using the list-connector-resources subcommand.
Example 13-5 Listing Connector Resources
This example lists the existing connector resources.
asadmin> list-connector-resources
jms/qConnFactory
Command list-connector-resources executed successfully
You can also view the full syntax and options of the subcommand by typing asadmin help list-connector-resources at the command line.
Use the get and set subcommands to view and change the values of the connector resource properties.
List the connector connection pools by using the list-connector-resources subcommand.
View the properties of the connector resource by using the get subcommand.
For example
asadmin> get domain.resources.connector-resource.jms/qConnFactory
Set the property of the connector resource by using the set subcommand.
For example:
asadmin> set domain.resources.connector-resource.jms/qConnFactory.enabled=true
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Use the delete-connector-resource subcommand in remote mode to remove a connector resource by specifying the JNDI name.
Before deleting a resource, all associations with the resource must be removed.
Ensure that the server is running.
Remote subcommands require a running server.
List the connector connection pools by using the list-connector-resources subcommand.
If necessary, notify users that the connector resource is being deleted.
Delete the connector resource by using the delete-connector-resource subcommand.
Example 13-6 Deleting a Connector Resource
This example deletes the jms/qConnFactory connector resource.
asadmin> delete-connector-resource jms/qConnFactory
Command delete-connector-resources executed successfully
You can also view the full syntax and options of the subcommand by typing asadmin help delete-connector-resource at the command line.
The following topics are addressed here:
Use the create-resource-adapter-config subcommand in remote mode to create configuration information for a resource adapter, also known as a connector module. You can run the subcommand before deploying a resource adapter, so that the configuration information is available at the time 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.
Ensure that the server is running.
Remote subcommands require a running server.
Create configuration information by using the create-resource-adapter-config subcommand.
Information about properties for the subcommand is included in this help page.
Example 13-7 Creating a Resource Adapter Configuration
This example creates the configuration for resource adapter ra1.
asadmin> create-resource-adapter-config --property foo=bar --threadpoolid mycustomerthreadpool ra1 Command create-resource-adapter-config executed successfully
You can also view the full syntax and options of the subcommand by typing asadmin help create-resource-adapter-config at the command line.
Use the list-resource-adapter-configs subcommand in remote mode to list the configuration information contained in the domain configuration file (domain.xml) for the specified resource adapter (connector module).
Ensure that the server is running.
Remote subcommands require a running server.
List the configurations for a resource adapter by using the list-resource-adapter-configs subcommand.
Example 13-8 Listing Configurations for a Resource Adapter
This example lists all the resource adapter configurations.
asadmin> list-resource-adapter-configs
ra1
ra2
Command list-resource-adapter-configs executed successfully
You can also view the full syntax and options of the subcommand by typing asadmin help list-resource-adapter-configs at the command line.
Use the get and set subcommands to view and change the values of the resource adapter configuration properties.
List the configurations for a resource adapter by using the list-resource-adapter-configs subcommand.
View the properties of the connector resource by using the get subcommand.
For example:
asadmin>get domain.resources.resource-adapter-config.ra1.*
Set the property of the connector resource by using the set subcommand.
For example:
asadmin> set domain.resources.resource-adapter-config.ra1.raSpecificProperty=value
Use the delete-resource-adapter-config subcommand in remote mode to delete the configuration information contained in the domain configuration file (domain.xml) for a specified resource adapter (connector module).
Ensure that the server is running.
Remote subcommands require a running server.
List the configurations for a resource adapter by using the list-resource-adapter-configs subcommand.
Delete the configuration for a resource adapter by using the delete-resource-adapter-config subcommand.
Example 13-9 Deleting a Resource Adapter Configuration
This example deletes the configuration for resource adapter ra1.
asadmin> delete-resource-adapter-config ra1
Command delete-resource-adapter-config executed successfully
You can also view the full syntax and options of the subcommand by typing asadmin help delete-resource-adapter-config at the command line.
The EIS is any system that holds the data of an organization. It can be a mainframe, a messaging system, a database system, or an application. The connector security map is used to map the application's credentials to the EIS credentials.
A security map applies to a particular connector connection pool. One or more named security maps can be associated with a connector connection pool.
The following topics are addressed here:
Use the create-connector-security-map subcommand in remote mode to create a security map for the specified connector connection pool. If the security map is not present, a new one is created. You can specify back-end EIS principals or back-end EIS user groups. The connector security map configuration supports the use of the wild card asterisk (*) to indicate all users or all user groups.
You can also use this subcommand to map the caller identity of the application (principal or user group) to a suitable EIS principal in container-managed authentication scenarios.
For this subcommand to succeed, you must have first created a connector connection pool. For instructions, see To Create a Connector Connection Pool.
Ensure that the server is running.
Remote subcommands require a running server.
Create a connector security map by using the create-connector-security-map subcommand.
Information about the options for the subcommand is included in this help page.
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Example 13-10 Creating a Connector Security Map
This example creates a connector security map securityMap1 for connection-pool1.
asadmin> create-connector-security-map --poolname connector-pool1 --principals principal1, principal2 --mappedusername backend-username securityMap1 Command create-connector-security-map executed successfully
Use the list-connector-security-maps subcommand in remote mode to list the existing security maps belonging to the specified connector 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.
Ensure that the server is running.
Remote subcommands require a running server.
List existing connector connection pools by using the list-connector-connection-pools subcommand.
List the security maps for a specific connector connection pool by using the list-connector-security-maps subcommand.
Example 13-11 Listing All Connector Security Maps for a Connector Connection Pool
This example lists the connector security maps associated with connector-Pool1.
asadmin> list-connector-security-maps connector-Pool1
securityMap1
Command list-connector-security-maps executed successfully.
Example 13-12 Listing Principals for a Specific Security Map for a Connector Connection Pool
This example lists the principals associated with securityMap1.
asadmin> list-connector-security-maps --securitymap securityMap1 connector-Pool1
principal1
principal1
Command list-connector-security-maps executed successfully.
Example 13-13 Listing Principals of All Connector Security Maps for a Connector Connection Pool
This example lists the connector security maps associated with connector-Pool1.
asadmin> list-connector-security-maps --verbose connector-Pool1
securityMap1
principal1
principal1
Command list-connector-security-maps executed successfully.
Use the update-connector-security-map subcommand in remote mode to create or modify a security map for the specified connector connection pool.
Ensure that the server is running.
Remote subcommands require a running server.
List existing connector security maps by using the list-connector-security-maps subcommand.
Modify a security map for a specific connector connection pool by using the update-connector-security-map subcommand.
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Use the delete-connector-security-map subcommand in remote mode to delete a security map for the specified connector connection pool.
Ensure that the server is running.
Remote subcommands require a running server.
List existing connector connection pools by using the list-connector-connection-pools subcommand.
Delete a security map for a specific connector connection pool by using the delete-connector-security-map subcommand.
Information about options for this subcommand is included in this help page.
The EIS is any system that holds the data of an organization. It can be a mainframe, a messaging system, a database system, or an application. The connector work security map is used to is used to map the EIS credentials to the credentials of GlassFish Server security domain.
A security map applies to a particular connector connection pool. One or more named security maps can be associated with a connector connection pool.
The following topics are addressed here:
Use the create-connector-work-security-map subcommand in remote mode to map the caller identity of the work submitted by the connector module (resource adapter) EIS principal or EIS user group to a suitable principal or user group in the GlassFish Server security domain. One or more work security maps can be associated with a connector module.
The connector security map configuration supports the use of the wild card asterisk (*) to indicate all users or all user groups.
Before creating a connector work security map, you must first create a connector connection pool. For instructions, see To Create a Connector Connection Pool.
Ensure that the server is running.
Remote subcommands require a running server.
Create the connector work security map by using the create-connector-work-security-map subcommand.
Information about properties for the subcommand is included in this help page.
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Example 13-16 Creating Connector Work Security Maps
The following examples create workSecurityMap1 and workSecurityMap2 for my-resource-adapter-name.
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 --groupsmap eis-group-1=server-group-1,eis-group-2=server-group-2, eis-group-3=server-group-1 workSecurityMap2 Command create-connector-work-security-map executed successfully
You can also view the full syntax and options of the subcommand by typing asadmin help create-connector-work-security-map at the command line.
Use the list-connector-work-security-maps subcommand in remote mode to list the work security maps that belong to a specific connector module.
Ensure that the server is running.
Remote subcommands require a running server.
List the connector work security maps by using the list-connector-work-security-maps subcommand.
Example 13-17 Listing the Connector Work Security Maps
This example lists the generic work security maps.
asadmin> list-connector-work-security-maps generic-ra generic-ra-groups-map: EIS group=eis-group, mapped group=glassfish-group generic-ra-principals-map: EIS principal=eis-bar, mapped principal=bar generic-ra-principals-map: EIS principal=eis-foo, mapped principal=foo Command list-connector-work-security-maps executed successfully.
You can also view the full syntax and options of the subcommand by typing asadmin help list-connector-work-security-maps at the command line.
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).
Ensure that the server is running.
Remote subcommands require a running server.
List the connector work security maps by using the list-connector-work-security-maps subcommand.
If necessary, notify users that the connector work security map is being modified.
Update a connector work security map by using the update-connector-work-security-map subcommand.
Example 13-18 Updating a Connector Work Security Map
This example removes a principal from a work security map.
asadmin> update-connector-work-security-map --raname generic-ra --removeprincipals eis-foo generic-ra-principals-map Command update-connector-work-security-map executed successfully.
You can also view the full syntax and options of the subcommand by typing asadmin help update-connector-work-security-map at the command line.
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).
Ensure that the server is running.
Remote subcommands require a running server.
List the connector work security maps by using the list-connector-work-security-maps subcommand.
Delete a connector work security map by using the delete-connector-work-security-map subcommand.
Example 13-19 Deleting a Connector Work Security Map
This example deletes the worksecuritymap1 map from the my_ra connector module.
asadmin> delete-connector-work-security-map --raname my_ra worksecuritymap1
Command delete-connector-work-security-map executed successfully.
You can also view the full syntax and options of the subcommand by typing asadmin help delete-connector-work-security-map at the command line.
Packaged within a connector module, an administered object provides specialized functionality for an application. For example, an administered object might provide access to a parser that is specific to the connector module and its associated EIS.
The following topics are addressed here:
Use the create-admin-object subcommand to create an administered object resource. When creating an administered object resource, name-value pairs are created, and the object is associated to a JNDI name.
The resource adapter must be deployed before running this subcommand (jmsrar.rar).
Create an administered object by using the create-admin-object subcommand.
Information about properties for the subcommand is included in this help page.
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Example 13-20 Creating an Administered Object
For this example, the javax.jms.Queue resource type is obtained from the ra.xml file. The JNDI name of the new administered object is jms/samplequeue.
asadmin> create-admin-object --restype javax.jms.Queue --raname jmsra --description "sample administered object" --property Name=sample_jmsqueue jms/samplequeue Command create-admin-object executed successfully
You can also view the full syntax and options of the subcommand by typing asadmin help create-admin-object at the command line.
Use the list-admin-object subcommand in remote mode to list the existing administered objects.
Ensure that the server is running.
Remote subcommands require a running server.
List the administered objects by using the list-admin-objects subcommand.
Example 13-21 Listing Administered Objects
This example lists the existing administered objects.
asadmin> list-admin-objects
jms/samplequeue
Command list-admin-objects executed successfully
You can also view the full syntax and options of the subcommand by typing asadmin help list-admin-object at the command line.
Use the get and set subcommands to view and change the values of the administered objects properties.
List the administered objects by using the list-admin-objects subcommand.
View the properties of the administered object by using the get subcommand.
For example:
asadmin> get domain.resources.admin-object-resource.jms/samplequeue.*
Set the property of the administered object by using the set subcommand.
For example:
asadmin> set domain.resources.admin-object-resource.jms/samplequeue.enabled=false
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Use the delete-admin-object subcommand to delete an administered objects.
List the administered objects by using the list-admin-objects subcommand.
If necessary, notify users that the administered object is being deleted.
Delete an administered object by using the delete-admin-object subcommand.
Example 13-22 Deleting an Administered Object
This example deletes the administered object with the JNDI name jms/samplequeue.
asadmin> delete-admin-object jms/samplequeue
Command delete-admin-object executed successfully
You can also view the full syntax and options of the subcommand by typing asadmin help delete-admin-object at the command line.
|
 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|