| type=page |
| status=published |
| title=Using the Java Naming and Directory Interface |
| next=jms.html |
| prev=transaction-service.html |
| ~~~~~~ |
| |
| = Using the Java Naming and Directory Interface |
| |
| [[GSDVG00019]][[beanr]] |
| |
| |
| [[using-the-java-naming-and-directory-interface]] |
| == 16 Using the Java Naming and Directory Interface |
| |
| A naming service maintains a set of bindings, which relate names to |
| objects. The Jakarta EE naming service is based on the Java Naming and |
| Directory Interface (JNDI) API. The JNDI API allows application |
| components and clients to look up distributed resources, services, and |
| EJB components. For general information about the JNDI API, see |
| `http://www.oracle.com/technetwork/java/jndi/index.html`. You can also |
| see the JNDI tutorial at `http://docs.oracle.com/javase/jndi/tutorial/`. |
| |
| The following topics are addressed here: |
| |
| * link:#beans[Accessing the Naming Context] |
| * link:#beanx[Configuring Resources] |
| * link:#gcpge[Using a Custom `jndi.properties` File] |
| * link:#beaoa[Mapping References] |
| |
| |
| [NOTE] |
| ==== |
| The Web Profile of the {productName} supports the EJB 3.1 Lite |
| specification, which allows enterprise beans within web applications, |
| among other features. The full {productName} supports the entire EJB |
| 3.1 specification. For details, see |
| http://jcp.org/en/jsr/detail?id=318[JSR 318] |
| (`http://jcp.org/en/jsr/detail?id=318`). |
| ==== |
| |
| |
| [[beans]][[GSDVG00192]][[accessing-the-naming-context]] |
| |
| === Accessing the Naming Context |
| |
| The {productName} provides a naming environment, or context, |
| which is compliant with standard Jakarta EE requirements. A `Context` |
| object provides the methods for binding names to objects, unbinding |
| names from objects, renaming objects, and listing the bindings. The |
| `InitialContext` is the handle to the Jakarta EE naming service that |
| application components and clients use for lookups. |
| |
| The JNDI API also provides subcontext functionality. Much like a |
| directory in a file system, a subcontext is a context within a context. |
| This hierarchical structure permits better organization of information. |
| For naming services that support subcontexts, the `Context` class also |
| provides methods for creating and destroying subcontexts. |
| |
| The following topics are addressed here: |
| |
| * link:#BGBJGGAD[Portable Global JNDI Names] |
| * link:#gcjkd[{productName} V2 Vendor-Specific Global JNDI Names] |
| * link:#gkndi[Disabling {productName} V2 JNDI Names] |
| * link:#beanu[Accessing EJB Components Using the `CosNaming` Naming |
| Context] |
| * link:#beanv[Accessing EJB Components in a Remote {productName}] |
| * link:#beanw[Naming Environment for Lifecycle Modules] |
| |
| |
| [NOTE] |
| ==== |
| Each resource within a server instance must have a unique name. However, |
| two resources in different server instances or different domains can |
| have the same name. |
| ==== |
| |
| |
| [[BGBJGGAD]][[GSDVG560]][[portable-global-jndi-names]] |
| |
| ==== Portable Global JNDI Names |
| |
| If an EJB component is a kind of session bean and it is deployed to any |
| implementation supporting the EJB 3.1specification (for example, |
| {productName} 7), it automatically has one or more portable JNDI |
| names defined based on the syntax in the specification. Note that this |
| is true of existing EJB 3.0 and 2.x applications that are deployed to an |
| implementation supporting EJB 3.1. No code changes are required to the |
| bean class itself in order to have the portable global JNDI name |
| automatically assigned when deployed to an EJB 3.1 container. |
| |
| For more information, see the Jakarta EE Platform Specification, section |
| EE.5.2.2, "Application Component Environment Namespaces" |
| (`http://jcp.org/en/jsr/detail?id=366`), |
| and the EJB 3.1 Specification, section 4.4, "Global JNDI Access" |
| (`http://jcp.org/en/jsr/detail?id=318`). |
| |
| If the `disable-nonportable-jndi-names` property is set to false (the |
| default), a {productName} V2-specific JNDI name is assigned in |
| addition to a portable global JNDI name. For more information, see |
| link:#gcjkd[{productName} V2 Vendor-Specific Global JNDI Names] and |
| link:#gkndi[Disabling {productName} V2 JNDI Names]. |
| |
| [[gcjkd]][[GSDVG00519]][[glassfish-server-v2-vendor-specific-global-jndi-names]] |
| |
| ==== {productName} V2 Vendor-Specific Global JNDI Names |
| |
| {productName} v2 vendor-specific global JNDI names are assigned |
| according to the following precedence rules: |
| |
| 1. A global JNDI name assigned in the `glassfish-ejb-jar.xml`, |
| `glassfish-web.xml`, or `glassfish-application-client.xml` deployment |
| descriptor file has the highest precedence. See link:#beaoa[Mapping |
| References]. |
| 2. A global JNDI name assigned in a `mapped-name` element in the |
| `ejb-jar.xml`, `web.xml`, or `application-client.xml` deployment |
| descriptor file has the second highest precedence. The following |
| elements have `mapped-name` subelements: `resource-ref`, |
| `resource-env-ref`, `ejb-ref`, `message-destination`, |
| `message-destination-ref`, `session`, `message-driven`, and `entity`. |
| 3. A global JNDI name assigned in a `mappedName` attribute of an |
| annotation has the third highest precedence. The following annotations |
| have `mappedName` attributes: `@jakarta.annotation.Resource`, |
| `@javax.ejb.EJB`, `@javax.ejb.Stateless`, `@javax.ejb.Singleton`, |
| `@javax.ejb.Stateful`, and `@javax.ejb.MessageDriven`. |
| 4. In most cases, a default global JNDI name is assigned (and recorded |
| in the server log) if no name is assigned in deployment descriptors or |
| annotations. |
| * For a session or entity bean, a {productName} V2-specific JNDI name |
| is assigned as follows: |
| |
| ** For an EJB 2.x dependency or a session or entity bean with a remote |
| interface, the default is the fully qualified name of the home |
| interface. |
| |
| ** For an EJB 3.0 dependency or a session bean with a remote interface, |
| the default is the fully qualified name of the remote business |
| interface. |
| |
| ** If both EJB 2.x and EJB 3.0 remote interfaces are specified, or if |
| more than one 3.0 remote interface is specified, there is no {productName} V2-specific default. For an entity bean, a global JNDI name must |
| be assigned. |
| * For all other component dependencies that must be mapped to global |
| JNDI names, the default is the name of the dependency relative to |
| `java:comp/env`. For example, in the |
| `@Resource(name="jdbc/Foo") DataSource ds;` annotation, the global JNDI |
| name is `jdbc/Foo`. |
| |
| [[gkndi]][[GSDVG00526]][[disabling-glassfish-server-v2-jndi-names]] |
| |
| ==== Disabling {productName} V2 JNDI Names |
| |
| The EJB 3.1 specification supported by {productName} 7 defines |
| portable EJB JNDI names for session beans. Because of this, there is |
| less need to continue to use older vendor-specific JNDI names. |
| |
| By default, {productName} V2-specific JNDI names are applied |
| automatically by {productName} 7 for backward compatibility. |
| However, this can lead to some ease-of-use issues. For example, |
| deploying two different applications containing a remote EJB component |
| that exposes the same remote interface causes a conflict between the |
| default JNDI names. |
| |
| The default handling of V2-specific JNDI names in {productName} 7 |
| can be managed by using the `asadmin` command: |
| |
| [source] |
| ---- |
| asadmin> set server.ejb-container.property.disable-nonportable-jndi-names="true" |
| ---- |
| |
| The `disable-nonportable-jndi-names` property is a boolean flag that can |
| take the following values: |
| |
| `false`:: |
| Enables the automatic use of {productName} V2-specific JNDI names |
| in addition to portable global JNDI names. This is the default |
| setting. |
| `true`:: |
| Disables the automatic use of V2-specific JNDI names. In all cases, |
| only portable global JNDI names are used. |
| |
| Note that this setting applies to all session beans deployed to the |
| server. |
| |
| [[beanu]][[GSDVG00520]][[accessing-ejb-components-using-the-cosnaming-naming-context]] |
| |
| ==== Accessing EJB Components Using the `CosNaming` Naming Context |
| |
| The preferred way of accessing the naming service, even in code that |
| runs outside of a Jakarta EE container, is to use the no-argument |
| `InitialContext` constructor. However, if EJB client code explicitly |
| instantiates an `InitialContext` that points to the `CosNaming` naming |
| service, it is necessary to set the `java.naming.factory.initial` |
| property to `org.glassfish.jndi.cosnaming.CNCtxFactory` in the client JVM |
| software when accessing EJB components. You can set this property using |
| the `asadmin create-jvm-options` command, as follows: |
| |
| [source] |
| ---- |
| asadmin> create-jvm-options -Djava.naming.factory.initial=org.glassfish.jndi.cosnaming.CNCtxFactory |
| ---- |
| |
| For details about `asadmin create-jvm-options`, see the |
| link:reference-manual.html#GSRFM[{productName} Reference Manual]. |
| |
| Or you can set this property in the code, as follows: |
| |
| [source,java] |
| ---- |
| Properties properties = null; |
| try { |
| properties = new Properties(); |
| properties.put("java.naming.factory.initial", |
| "org.glassfish.jndi.cosnaming.CNCtxFactory"); |
| ... |
| } |
| ... |
| ---- |
| |
| The `java.naming.factory.initial` property applies to only one instance. |
| The property is not cluster-aware. |
| |
| [[beanv]][[GSDVG00521]][[accessing-ejb-components-in-a-remote-glassfish-server]] |
| |
| ==== Accessing EJB Components in a Remote {productName} |
| |
| The recommended approach for looking up an EJB component in a remote |
| {productName} from a client that is a servlet or EJB component is to |
| use the Interoperable Naming Service syntax. Host and port information |
| is prepended to any global JNDI names and is automatically resolved |
| during the lookup. The syntax for an interoperable global name is as |
| follows: |
| |
| [source] |
| ---- |
| corbaname:iiop:host:port#a/b/name |
| ---- |
| |
| This makes the programming model for accessing EJB components in another |
| {productName} exactly the same as accessing them in the same server. |
| The deployer can change the way the EJB components are physically |
| distributed without having to change the code. |
| |
| For Jakarta EE components, the code still performs a `java:comp/env` lookup |
| on an EJB reference. The only difference is that the deployer maps the |
| `ejb-ref` element to an interoperable name in a {productName} |
| deployment descriptor file instead of to a simple global JNDI name. |
| |
| For example, suppose a servlet looks up an EJB reference using |
| `java:comp/env/ejb/Foo`, and the target EJB component has a global JNDI |
| name of `a/b/Foo`. |
| |
| The `ejb-ref` element in `glassfish-web.xml` looks like this: |
| |
| [source,xml] |
| ---- |
| <ejb-ref> |
| <ejb-ref-name>ejb/Foo</ejb-ref-name> |
| <jndi-name>corbaname:iiop:host:port#a/b/Foo</jndi-name> |
| </ejb-ref> |
| ---- |
| |
| The code looks like this: |
| |
| [source,java] |
| ---- |
| Context ic = new InitialContext(); |
| Object o = ic.lookup("java:comp/env/ejb/Foo"); |
| ---- |
| |
| For a client that doesn't run within a Jakarta EE container, the code just |
| uses the interoperable global name instead of the simple global JNDI |
| name. For example: |
| |
| [source,java] |
| ---- |
| Context ic = new InitialContext(); |
| Object o = ic.lookup("corbaname:iiop:host:port#a/b/Foo"); |
| ---- |
| |
| Objects stored in the interoperable naming context and |
| component-specific (`java:comp/env`) naming contexts are transient. On |
| each server startup or application reloading, all relevant objects are |
| re-bound to the namespace. |
| |
| [[beanw]][[GSDVG00522]][[naming-environment-for-lifecycle-modules]] |
| |
| ==== Naming Environment for Lifecycle Modules |
| |
| Lifecycle listener modules provide a means of running short or long |
| duration tasks based on Java technology within the {productName} |
| environment, such as instantiation of singletons or RMI servers. These |
| modules are automatically initiated at server startup and are notified |
| at various phases of the server life cycle. For details about lifecycle |
| modules, see link:lifecycle-listeners.html#beamc[Developing Lifecycle |
| Listeners]. |
| |
| The configured properties for a lifecycle module are passed as |
| properties during server initialization (the `INIT_EVENT`). The initial |
| JNDI naming context is not available until server initialization is |
| complete. A lifecycle module can get the `InitialContext` for lookups |
| using the method `LifecycleEventContext.getInitialContext()` during, and |
| only during, the `STARTUP_EVENT`, `READY_EVENT`, or `SHUTDOWN_EVENT` |
| server life cycle events. |
| |
| [[beanx]][[GSDVG00193]][[configuring-resources]] |
| |
| === Configuring Resources |
| |
| The {productName} exposes special resources in the naming |
| environment. |
| |
| * link:#beany[External JNDI Resources] |
| * link:#beanz[Custom Resources] |
| * link:#giyvw[Built-in Factories for Custom Resources] |
| * link:#gkpdn[Using Application-Scoped Resources] |
| |
| [[beany]][[GSDVG00523]][[external-jndi-resources]] |
| |
| ==== External JNDI Resources |
| |
| An external JNDI resource defines custom JNDI contexts and implements |
| the javax.naming.spi.InitialContextFactory interface. There is no |
| specific JNDI parent context for external JNDI resources, except for the |
| standard `java:comp/env/`. |
| |
| Create an external JNDI resource in one of these ways: |
| |
| * To create an external JNDI resource using the Administration Console, |
| open the Resources component, open the JNDI component, and select |
| External Resources. For details, click the Help button in the |
| Administration Console. |
| * To create an external JNDI resource, use the |
| `asadmin create-jndi-resource` command. For details, see the |
| link:reference-manual.html#GSRFM[{productName} Reference Manual]. |
| |
| [[beanz]][[GSDVG00524]][[custom-resources]] |
| |
| ==== Custom Resources |
| |
| A custom resource specifies a custom server-wide resource object factory |
| that implements the javax.naming.spi.ObjectFactory interface. There is |
| no specific JNDI parent context for external JNDI resources, except for |
| the standard `java:comp/env/`. |
| |
| Create a custom resource in one of these ways: |
| |
| * To create a custom resource using the Administration Console, open the |
| Resources component, open the JNDI component, and select Custom |
| Resources. For details, click the Help button in the Administration |
| Console. |
| * To create a custom resource, use the `asadmin create-custom-resource` |
| command. For details, see the link:reference-manual.html#GSRFM[{productName} Reference Manual]. |
| |
| [[giyvw]][[GSDVG00525]][[built-in-factories-for-custom-resources]] |
| |
| ==== Built-in Factories for Custom Resources |
| |
| The {productName} provides built-in factories for the following types |
| of custom resources: |
| |
| * link:#giywi[JavaBeanFactory] |
| * link:#giysn[PropertiesFactory] |
| * link:#giytz[PrimitivesAndStringFactory] |
| * link:#giywh[URLFactory] |
| |
| Template `glassfish-resources.xml` files for these built-in factories |
| and a `README` file are available at |
| as-install``/lib/install/templates/resources/custom/``. For more |
| information about the `glassfish-resources.xml` file, see the |
| link:application-deployment-guide.html#GSDPG[{productName} Application Deployment |
| Guide]. |
| |
| [[giywi]][[GSDVG00329]][[javabeanfactory]] |
| |
| ===== JavaBeanFactory |
| |
| To create a custom resource that provides instances of a JavaBean class, |
| follow these steps: |
| |
| 1. Set the custom resource's factory class to |
| `org.glassfish.resources.custom.factory.JavaBeanFactory`. |
| 2. Create a property in the custom resource for each setter method in |
| the JavaBean class. |
| + |
| For example, if the JavaBean class has a method named `setAccount`, |
| specify a property named `account` and give it a value. |
| 3. Make sure the JavaBean class is accessible to the {productName}. |
| + |
| For example, you can place the JavaBean class in the as-install``/lib`` |
| directory. |
| |
| [[giysn]][[GSDVG00330]][[propertiesfactory]] |
| |
| ===== PropertiesFactory |
| |
| To create a custom resource that provides properties to applications, |
| set the custom resource's factory class to |
| `org.glassfish.resources.custom.factory.PropertiesFactory`, then specify |
| one or both of the following: |
| |
| * Create a property in the custom resource named |
| `org.glassfish.resources.custom.factory.PropertiesFactory.fileName` and |
| specify as its value the path to a properties file or an XML file. |
| + |
| The path can be absolute or relative to as-install. The file must be |
| accessible to the {productName}. |
| + |
| If an XML file is specified, it must match the document type definition |
| (DTD) specified in the API definition of |
| http://download.oracle.com/javase/8/docs/api/java/util/Properties.html[java.util.Properties] |
| (`http://docs.oracle.com/javase/8/docs/api/java/util/Properties.html`). |
| * Create the desired properties directly as properties of the custom |
| resource. |
| + |
| If both the `fileName` property and other properties are specified, the |
| resulting property set is the union. If the same property is defined in |
| the file and directly in the custom resource, the value of the latter |
| takes precedence. |
| |
| [[giytz]][[GSDVG00331]][[primitivesandstringfactory]] |
| |
| ===== PrimitivesAndStringFactory |
| |
| To create a custom resource that provides Java primitives to |
| applications, follow these steps: |
| |
| 1. Set the custom resource's factory class to |
| `org.glassfish.resources.custom.factory.PrimitivesAndStringFactory`. |
| 2. Set the custom resource's resource type to one of the following or |
| its fully qualified wrapper class name equivalent: |
| * `int` |
| * `long` |
| * `double` |
| * `float` |
| * `char` |
| * `short` |
| * `byte` |
| * `boolean` |
| * `String` |
| 3. Create a property in the custom resource named `value` and give it |
| the value needed by the application. |
| + |
| For example, If the application requires a `double` of value `22.1`, |
| create a property with the name `value` and the value `22.1`. |
| |
| [[giywh]][[GSDVG00332]][[urlfactory]] |
| |
| ===== URLFactory |
| |
| To create a custom resource that provides URL instances to applications, |
| follow these steps: |
| |
| 1. Set the custom resource's factory class to |
| `org.glassfish.resources.custom.factory.URLObjectFactory`. |
| 2. Choose which of the following constructors to use: |
| * `URL(protocol, host, port, file)` |
| * `URL(protocol, host, file)` |
| * `URL(spec)` |
| 3. Define properties according to the chosen constructor. |
| + |
| For example, for the first constructor, define properties named |
| `protocol`, `host`, `port`, and `file`. Example values might be `http`, |
| `localhost`, `8085`, and `index.html`, respectively. |
| + |
| For the third constructor, define a property named `spec` and assign it |
| the value of the entire URL. |
| |
| [[gkpdn]][[GSDVG00527]][[using-application-scoped-resources]] |
| |
| ==== Using Application-Scoped Resources |
| |
| You can define an application-scoped JNDI or other resource for an |
| enterprise application, web module, EJB module, connector module, or |
| application client module by supplying a `glassfish-resources.xml` |
| deployment descriptor file. For details, see |
| "link:application-deployment-guide/deploying-applications.html#GSDPG00075[Application-Scoped Resources]" in {productName} Application Deployment Guide. |
| |
| [[gcpge]][[GSDVG00194]][[using-a-custom-jndi.properties-file]] |
| |
| === Using a Custom `jndi.properties` File |
| |
| To use a custom `jndi.properties` file, JAR it and place it in the |
| domain-dir``/lib`` directory. This adds the custom `jndi.properties` file |
| to the Common class loader. For more information about class loading, |
| see link:class-loaders.html#beade[Class Loaders]. |
| |
| For each property found in more than one `jndi.properties` file, the |
| Jakarta EE naming service either uses the first value found or concatenates |
| all of the values, whichever makes sense. |
| |
| [[beaoa]][[GSDVG00195]][[mapping-references]] |
| |
| === Mapping References |
| |
| The following XML elements in the {productName} deployment |
| descriptors map resource references in application client, EJB, and web |
| application components to JNDI names configured in {productName}: |
| |
| * `resource-env-ref` - Maps the `@Resource` or `@Resources` annotation |
| (or the `resource-env-ref` element in the corresponding Jakarta EE XML |
| file) to the absolute JNDI name configured in {productName}. |
| * `resource-ref` - Maps the `@Resource` or `@Resources` annotation (or |
| the `resource-ref` element in the corresponding Jakarta EE XML file) to the |
| absolute JNDI name configured in {productName}. |
| * `ejb-ref` - Maps the `@EJB` annotation (or the `ejb-ref` element in |
| the corresponding Jakarta EE XML file) to the absolute JNDI name configured |
| in {productName}. |
| + |
| JNDI names for EJB components must be unique. For example, appending the |
| application name and the module name to the EJB name is one way to |
| guarantee unique names. In this case, `mycompany.pkging.pkgingEJB.MyEJB` |
| would be the JNDI name for an EJB in the module `pkgingEJB.jar`, which |
| is packaged in the `pkging.ear` application. |
| |
| These elements are part of the `glassfish-web.xml`, |
| `glassfish-application-client.xml`, `glassfish-ejb-jar.xml`, and |
| `glassfish-application.xml` deployment descriptor files. For more |
| information about how these elements behave in each of the deployment |
| descriptor files, see "link:application-deployment-guide/dd-elements.html#GSDPG00007[Elements of the {productName} |
| Deployment Descriptors]" in {productName} |
| Application Deployment Guide. |
| |
| The rest of this section uses an example of a JDBC resource lookup to |
| describe how to reference resource factories. The same principle is |
| applicable to all resources (such as JMS destinations, JavaMail |
| sessions, and so on). |
| |
| The `@Resource` annotation in the application code looks like this: |
| |
| [source,java] |
| ---- |
| @Resource(name="jdbc/helloDbDs") javax.sql.DataSource ds; |
| ---- |
| |
| This references a resource with the JNDI name of `java:jdbc/helloDbDs`. |
| If this is the JNDI name of the JDBC resource configured in the |
| {productName}, the annotation alone is enough to reference the |
| resource. |
| |
| However, you can use a {productName} specific deployment descriptor |
| to override the annotation. For example, the `resource-ref` element in |
| the `glassfish-web.xml` file maps the `res-ref-name` (the name specified |
| in the annotation) to the JNDI name of another JDBC resource configured |
| in {productName}. |
| |
| [source,xml] |
| ---- |
| <resource-ref> |
| <res-ref-name>jdbc/helloDbDs</res-ref-name> |
| <jndi-name>jdbc/helloDbDataSource</jndi-name> |
| </resource-ref> |
| ---- |
| |
| |