Resource Creation

In a distributed application, components need to access other components and resources, such as databases. For example, a servlet might invoke remote methods on an enterprise bean that retrieves information from a database. In the Jakarta EE platform, the Java Naming and Directory Interface (JNDI) naming service enables components to locate other components and resources.

A resource is a program object that provides connections to systems, such as database servers and messaging systems. A Java Database Connectivity resource is sometimes referred to as a data source. Each resource object is identified by a unique, people-friendly name, called the JNDI name. For example, the JNDI name of the preconfigured JDBC resource for Apache Derby shipped with GlassFish Server is java:comp/DefaultDataSource.

An administrator creates resources in a JNDI namespace. In GlassFish Server, you can use either the Administration Console or the asadmin command to create resources. Applications then use annotations to inject the resources. If an application uses resource injection, GlassFish Server invokes the JNDI API, and the application is not required to do so. However, it is also possible for an application to locate resources by making direct calls to the JNDI API.

A resource object and its JNDI name are bound together by the naming and directory service. To create a new resource, a new name/object binding is entered into the JNDI namespace. You inject resources by using the @Resource annotation in an application.

You can use a deployment descriptor to override the resource mapping that you specify in an annotation. Using a deployment descriptor allows you to change an application by repackaging it rather than by both recompiling the source files and repackaging. However, for most applications a deployment descriptor is not necessary.

To store, organize, and retrieve data, most applications use a relational database. Jakarta EE components may access relational databases through the JDBC API. For information on this API, see https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/.

In the JDBC API, databases are accessed by using DataSource objects. A DataSource has a set of properties that identify and describe the real-world data source that it represents. These properties include such information as the location of the database server, the name of the database, the network protocol to use to communicate with the server, and so on. In GlassFish Server, a data source is called a JDBC resource.

Applications access a data source by using a connection, and a DataSource object can be thought of as a factory for connections to the particular data source that the DataSource instance represents. In a basic DataSource implementation, a call to the getConnection method returns a connection object that is a physical connection to the data source.

A DataSource object may be registered with a JNDI naming service. If so, an application can use the JNDI API to access that DataSource object, which can then be used to connect to the data source it represents.

DataSource objects that implement connection pooling also produce a connection to the particular data source that the DataSource class represents. The connection object that the getConnection method returns is a handle to a PooledConnection object rather than a physical connection. An application uses the connection object in the same way that it uses a connection. Connection pooling has no effect on application code except that a pooled connection, like all connections, should always be explicitly closed. When an application closes a connection that is pooled, the connection is returned to a pool of reusable connections. The next time getConnection is called, a handle to one of these pooled connections will be returned if one is available. Because connection pooling avoids creating a new physical connection every time one is requested, applications can run significantly faster.

A JDBC connection pool is a group of reusable connections for a particular database. Because creating each new physical connection is time consuming, the server maintains a pool of available connections to increase performance. When it requests a connection, an application obtains one from the pool. When an application closes a connection, the connection is returned to the pool.

Applications that use Jakarta Persistence specify the DataSource object they are using in the jta-data-source element of the persistence.xml file:

This is typically the only reference to a JDBC object for a persistence unit. The application code does not refer to any JDBC objects.

Before you deploy or run many applications, you may need to create resources for them. An application can include a glassfish-resources.xml file that can be used to define resources for that application and others. You can then use the asadmin command, specifying as the argument a file named glassfish-resources.xml, to create the resources administratively, as shown.

The glassfish-resources.xml file can be created in any project using NetBeans IDE or by hand. Some of the Jakarta Messaging examples use this approach to resource creation. A file for creating the resources needed for the Messaging simple producer example can be found in the jms/simple/producer/src/main/setup directory.

You could also use the asadmin create-jms-resource command to create the resources for this example. When you are done using the resources, you would use the asadmin list-jms-resources command to display their names, and the asadmin delete-jms-resource command to remove them, regardless of the way you created the resources.