type=page
status=published
title=Administering EIS Connectivity
next=http_https.html
prev=jdbc.html
~~~~~~

Administering EIS Connectivity
==============================

[[GSADG00016]][[abllp]]


[[administering-eis-connectivity]]
12 Administering EIS Connectivity
---------------------------------

This chapter provides information and procedures for administering
connections to enterprise information system (EIS) data in the Oracle
GlassFish Server 5.0 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:

* link:#abllq[About EIS Connectivity]
* link:#ablls[Administering Connector Connection Pools]
* link:#abllx[Administering Connector Resources]
* link:#giope[Administering the Resource Adapter Configuration]
* link:#gitxy[Administering Connector Security Maps]
* link:#giohl[Administering Connector Work Security Maps]
* link:#ablmc[Administering Administered Objects]

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
link:jdbc.html#ablih[Administering Database Connectivity].

[[abllq]][[GSADG00580]][[about-eis-connectivity]]

About EIS 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 "link:../application-development-guide/connectors.html#GSDVG00013[Developing Connectors]" in
GlassFish Server Open Source Edition 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 link:#ablls[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 link:#abllx[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 link:#giope[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
link:#gitxy[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 link:#giohl[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 link:#ablmc[Administering Administered
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.
+
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.
+
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.
+
The application accesses the EIS information by making calls to the JMS
API.
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]]

Administering Connector Connection Pools
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After a connector module has been deployed, you are ready to create a
connector connection pool for it.

The following topics are addressed here:

* link:#gioce[To Create a Connector Connection Pool]
* link:#giocg[To List Connector Connection Pools]
* link:#gjiqz[To Connect to (Ping) or Reset (Flush) a Connector
Connection Pool]
* link:#gioti[To Update a Connector Connection Pool]
* link:#giocp[To Delete a Connector Connection Pool]

[[gioce]][[GSADG00431]][[to-create-a-connector-connection-pool]]

To Create a Connector Connection Pool
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 link:overview.html#ghciy[Configuration
Changes That Require Restart].

[[GSADG968]]

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.
+
Information about properties for the subcommand is included in this help
page.
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.
+
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]
----
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
----

[[GSADG969]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help create-connector-connection-pool` at the command
line.

[[giocg]][[GSADG00432]][[to-list-connector-connection-pools]]

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
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]
----
asadmin> list-connector-connection-pools
jms/qConnPool
Command list-connector-connection-pools executed successfully
----

[[GSADG970]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help list-connector-connection-pools` at the command
line.

[[gjiqz]][[GSADG00433]][[to-connect-to-ping-or-reset-flush-a-connector-connection-pool]]

To Connect to (Ping) or Reset (Flush) a Connector Connection Pool
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use the `ping-connection-pool` or `flush-connection-pool` subcommands in
remote mode to perform these tasks on a connection pools. See
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
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.

[[gioti]][[GSADG00434]][[to-update-a-connector-connection-pool]]

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
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]
----
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]
----
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].

[[giocp]][[GSADG00435]][[to-delete-a-connector-connection-pool]]

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
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
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]
----
asadmin> delete-connector-connection-pool --cascade=false jms/qConnPool
Command delete-connector-connection-pool executed successfully
----

[[GSADG971]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help delete-connector-connection-pool` at the command
line.

[[abllx]][[GSADG00582]][[administering-connector-resources]]

Administering Connector Resources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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:

* link:#giogt[To Create a Connector Resource]
* link:#giohs[To List Connector Resources]
* link:#giosg[To Update a Connector Resource]
* link:#giofs[To Delete a Connector Resource]

[[giogt]][[GSADG00436]][[to-create-a-connector-resource]]

To Create a Connector Resource
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 link:overview.html#ghciy[Configuration Changes That
Require Restart].

[[GSADG972]]

Before You Begin

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.
+
Information about properties for the subcommand is included in this help
page.
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]
----
asadmin> create-connector-resource --poolname jms/qConnPool
--description "creating sample connector resource" jms/qConnFactory
Command create-connector-resource executed successfully
----

[[GSADG973]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help create-connector-resource` at the command line.

[[giohs]][[GSADG00437]][[to-list-connector-resources]]

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
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]
----
asadmin> list-connector-resources
jms/qConnFactory
Command list-connector-resources executed successfully
----

[[GSADG974]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help list-connector-resources` at the command line.

[[giosg]][[GSADG00438]][[to-update-a-connector-resource]]

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
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]
----
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]
----
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].

[[giofs]][[GSADG00439]][[to-delete-a-connector-resource]]

To Delete a Connector Resource
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use the `delete-connector-resource` subcommand in remote mode to remove
a connector resource by specifying the JNDI name.

[[GSADG975]]

Before You Begin

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
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
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]
----
asadmin> delete-connector-resource jms/qConnFactory
Command delete-connector-resources executed successfully
----

[[GSADG976]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help delete-connector-resource` at the command line.

[[giope]][[GSADG00583]][[administering-the-resource-adapter-configuration]]

Administering the Resource Adapter Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following topics are addressed here:

* link:#gioqx[To Create Configuration Information for a Resource
Adapter]
* link:#giorn[To List Resource Adapter Configurations]
* link:#gioum[To Update a Resource Adapter Configuration]
* link:#gionv[To Delete a Resource Adapter Configuration]

[[gioqx]][[GSADG00440]][[to-create-configuration-information-for-a-resource-adapter]]

To Create Configuration Information for a Resource Adapter
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.

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]
----
asadmin> create-resource-adapter-config --property foo=bar
--threadpoolid mycustomerthreadpool ra1
Command create-resource-adapter-config executed successfully
----

[[GSADG977]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help create-resource-adapter-config` at the command
line.

[[giorn]][[GSADG00441]][[to-list-resource-adapter-configurations]]

To List Resource Adapter Configurations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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).

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]
----
asadmin> list-resource-adapter-configs
ra1
ra2
Command list-resource-adapter-configs executed successfully
----

[[GSADG978]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help list-resource-adapter-configs` at the command line.

[[gioum]][[GSADG00442]][[to-update-a-resource-adapter-configuration]]

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
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]
----
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]
----
asadmin> set domain.resources.resource-adapter-config.ra1.raSpecificProperty=value
----

[[gionv]][[GSADG00443]][[to-delete-a-resource-adapter-configuration]]

To Delete a Resource Adapter Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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).

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
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]
----
asadmin> delete-resource-adapter-config ra1
Command delete-resource-adapter-config executed successfully
----

[[GSADG979]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help delete-resource-adapter-config` at the command
line.

[[gitxy]][[GSADG00584]][[administering-connector-security-maps]]

Administering Connector Security Maps
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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:

* link:#gitzz[To Create a Connector Security Map]
* link:#gitwx[To List Connector Security Maps]
* link:#gityj[To Update a Connector Security Map]
* link:#gitvf[To Delete a Connector Security Map]

[[gitzz]][[GSADG00444]][[to-create-a-connector-security-map]]

To Create a Connector Security Map
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.

[[GSADG980]]

Before You Begin

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.
+
Information about the options for the subcommand is included in this
help page.
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]
----
asadmin> create-connector-security-map --poolname connector-pool1
--principals principal1, principal2 --mappedusername backend-username securityMap1
Command create-connector-security-map executed successfully
----

[[gitwx]][[GSADG00445]][[to-list-connector-security-maps]]

To List Connector Security Maps
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.

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
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]
----
asadmin> list-connector-security-maps connector-Pool1
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]
----
asadmin> list-connector-security-maps --securitymap securityMap1 connector-Pool1
principal1
principal1
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]
----
asadmin> list-connector-security-maps --verbose connector-Pool1
securityMap1
principal1
principal1
Command list-connector-security-maps executed successfully.
----

[[gityj]][[GSADG00446]][[to-update-a-connector-security-map]]

To Update a Connector Security Map
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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
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
using the link:../reference-manual/update-connector-security-map.html#GSRFM00252[`update-connector-security-map`] subcommand.
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]
----
asadmin> update-connector-security-map --poolname connector-pool1
--addprincipals principal1, principal2 securityMap1
Command update-connector-security-map executed successfully.
----

[[gitvf]][[GSADG00447]][[to-delete-a-connector-security-map]]

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
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.
+
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]
----
asadmin> delete-connector-security-map --poolname connector-pool1 securityMap1

Command delete-connector-security-map executed successfully
----

[[giohl]][[GSADG00585]][[administering-connector-work-security-maps]]

Administering Connector Work Security Maps
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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:

* link:#giofz[To Create a Connector Work Security Map]
* link:#gioir[To List Connector Work Security Maps]
* link:#giogm[To Update a Connector Work Security Map]
* link:#gioin[To Delete a Connector Work Security Map]

[[giofz]][[GSADG00448]][[to-create-a-connector-work-security-map]]

To Create a Connector Work Security Map
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.

[[GSADG981]]

Before You Begin

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.
+
Information about properties for the subcommand is included in this help
page.
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]
----
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
----

[[GSADG982]]

See Also

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.

[[gioir]][[GSADG00449]][[to-list-connector-work-security-maps]]

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
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]
----
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.
----

[[GSADG983]]

See Also

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.

[[giogm]][[GSADG00450]][[to-update-a-connector-work-security-map]]

To Update a Connector Work Security Map
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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
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
being modified.
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]
----
asadmin> update-connector-work-security-map --raname generic-ra
--removeprincipals eis-foo generic-ra-principals-map
Command update-connector-work-security-map executed successfully.
----

[[GSADG984]]

See Also

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.

[[gioin]][[GSADG00451]][[to-delete-a-connector-work-security-map]]

To Delete a Connector Work Security Map
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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
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
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]
----
asadmin> delete-connector-work-security-map --raname my_ra worksecuritymap1
Command delete-connector-work-security-map executed successfully.
----

[[GSADG985]]

See Also

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.

[[ablmc]][[GSADG00586]][[administering-administered-objects]]

Administering Administered Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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:

* link:#giolr[To Create an Administered Object]
* link:#giokm[To List Administered Objects]
* link:#giots[To Update an Administered Object]
* link:#gioma[To Delete an Administered Object]

[[giolr]][[GSADG00452]][[to-create-an-administered-object]]

To Create an Administered Object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.

[[GSADG986]]

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.
+
Information about properties for the subcommand is included in this help
page.
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]
----
asadmin> create-admin-object --restype jakarta.jms.Queue --raname jmsra
--description "sample administered object" --property Name=sample_jmsqueue jms/samplequeue
Command create-admin-object executed successfully
----

[[GSADG987]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help create-admin-object` at the command line.

[[giokm]][[GSADG00453]][[to-list-administered-objects]]

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
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]
----
asadmin> list-admin-objects
jms/samplequeue
Command list-admin-objects executed successfully
----

[[GSADG988]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help list-admin-object` at the command line.

[[giots]][[GSADG00454]][[to-update-an-administered-object]]

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
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]
----
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]
----
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].

[[gioma]][[GSADG00455]][[to-delete-an-administered-object]]

To Delete an Administered Object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use the `delete-admin-object` subcommand to delete an administered objects.

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
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]
----
asadmin> delete-admin-object jms/samplequeue
Command delete-admin-object executed successfully
----

[[GSADG989]]

See Also

You can also view the full syntax and options of the subcommand by
typing `asadmin help delete-admin-object` at the command line.