Bind an Application to a NoSQL Resource

Binding establishes the deployer approved destination. Before deployment, configure a valid local target resource and the intended access policy.

Understand the Binding Chain

The Jakarta Data and NoSQL code sample’s PersonRepository uses the local alias declared in WEB-INF/web.xml. WEB-INF/weblogic.xml maps that alias to the JNDI binding configured by configure-nosql.py.

@Repository(dataStore = "nosql/person")
  -> resource-ref or resource-env-ref named nosql/person
     type: org.eclipse.jnosql.communication.semistructured.DatabaseManager
  -> matching WebLogic JNDI mapping
     jndi-name: nosql/personNoSqlResource
  -> global descriptor with that binding
     management resource: personNoSqlResource; locally targeted

A resource-ref requires a resource-description mapping. A resource-env-ref requires a resource-env-description mapping. Keep the declaration and mapping in the same effective application, module, or EJB scope.

Match the Effective Scope

Use the declaration and mapping pair for the same effective scope.

Declaration Scope	Matching Mapping Scope	Requirement
Application	Corresponding application-level WebLogic descriptor	Same application and alias
WAR	That WAR’s `WEB-INF/weblogic.xml`	Same WAR and alias
EJB	Corresponding `weblogic-enterprise-bean` entry	Same `ejb-name` and alias

Matching alias text in different scopes does not establish a binding. Review the effective descriptors after plan overrides, including application, module, and EJB identities. The WAR and EJB fragments below do not establish its complete syntax.

Package a WAR Binding

The sample’s WEB-INF/web.xml declares the following reference. Its descriptor uses the Jakarta Servlet 6.1 schema.

<resource-ref>
  <res-ref-name>nosql/person</res-ref-name>
  <res-type>org.eclipse.jnosql.communication.semistructured.DatabaseManager</res-type>
  <res-auth>Container</res-auth>
  <res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>

The sample’s WEB-INF/weblogic.xml supplies the corresponding mapping in the same WAR.

<resource-description>
  <res-ref-name>nosql/person</res-ref-name>
  <jndi-name>nosql/personNoSqlResource</jndi-name>
</resource-description>

The JNDI name must match exactly one valid, locally targeted global descriptor. A mapping in another WAR does not complete this declaration.

Package an EJB Binding

The following descriptor fragments illustrate an EJB-scoped reference and its matching WebLogic mapping. PersonService and PersonServiceBean are illustrative application classes. The example uses the local alias nosql/person and the global resource’s JNDI binding nosql/personNoSqlResource introduced in this book.

Add the standard reference under the consuming bean’s session entry in META-INF/ejb-jar.xml.

<session>
  <ejb-name>PersonServiceBean</ejb-name>
  <business-local>examples.jakartaee.nosql.PersonService</business-local>
  <ejb-class>examples.jakartaee.nosql.PersonServiceBean</ejb-class>
  <session-type>Stateless</session-type>
  <transaction-type>Container</transaction-type>
  <resource-ref>
    <res-ref-name>nosql/person</res-ref-name>
    <res-type>org.eclipse.jnosql.communication.semistructured.DatabaseManager</res-type>
    <res-auth>Container</res-auth>
    <res-sharing-scope>Shareable</res-sharing-scope>
  </resource-ref>
</session>

Map the reference under the same EJB identity in META-INF/weblogic-ejb-jar.xml.

<weblogic-enterprise-bean>
  <ejb-name>PersonServiceBean</ejb-name>
  <resource-description>
    <res-ref-name>nosql/person</res-ref-name>
    <jndi-name>nosql/personNoSqlResource</jndi-name>
  </resource-description>
</weblogic-enterprise-bean>

These are fragments, not complete deployment descriptors. Merge them into the applicable roots and namespaces. Another bean’s mapping or a sibling WAR’s mapping does not satisfy the same scope requirement.

Apply a Deployment-Plan Override

Complete packaged declarations and mappings work without a deployment plan. Use a plan when the target environment needs a different mapping.

Identify the module and WebLogic descriptor containing the mapping.
Create a plan assignment for the alias’s JNDI mapping.
Set the assignment to the destination resource’s JNDI name.
Verify the complete effective declaration and mapping.
Deploy the application with the plan.

The following comparison uses the shipped WAR’s packaged mapping. The production destination is illustrative and is not a definition supplied by the sample.

Effective Item	Packaged Sample	Illustrative Environment Override
Module	`data-nosql.war`	`data-nosql.war`
Descriptor	`WEB-INF/weblogic.xml`	`WEB-INF/weblogic.xml`
Alias	`nosql/person`	`nosql/person`
JNDI mapping	`nosql/personNoSqlResource`	`nosql/personProductionResource`

Configure the illustrative destination as a separate valid, locally targeted global resource before using that override. Generate the variable assignment with the deployment plan tooling and verify its module selector and descriptor XPath. The table describes intended effective values; it is not copyable plan syntax.

Preserve the alias, required type, and effective scope. A plan does not waive a missing declaration, wrong type, ambiguous destination, or authorization check.

Select a Default Resource

When dataStore is omitted, selection requires exactly one valid, locally targeted resource explicitly bound to the application and marked DefaultResource=true.

A sole visible global resource or a sole bound non-default resource is not a fallback. Explicit alias selection does not require the resource to be a default.

All repositories in one deployment using the WebLogic NoSQL system resource path must select one bound global identity. The binding and global identity remain fixed for that deployment generation; compatible configuration generations can advance.

Diagnose a Binding Failure

WebLogic Server rejects missing, conflicting, blank, ambiguous, and cross-scope mappings. It also rejects direct global-name/global-JNDI selection in place of a local alias, mapped-name alone, an unmatched WebLogic Server mapping, and resource-link.

Use the following checks to distinguish rejected binding conditions.

Rejected Condition	Required Correction	Verification
Missing declaration, `mapped-name` alone, or WebLogic Server mapping alone	Supply the complete declaration and mapping	Same effective scope and alias
Wrong reference type	Declare `org.eclipse.jnosql.communication.semistructured.DatabaseManager`	Effective standard descriptor
Mismatched reference/mapping kinds	Pair `resource-ref` with `resource-description`, or `resource-env-ref` with `resource-env-description`	Matching pair in effective descriptors
`resource-link`	Use the supported explicit JNDI mapping	Mapping contains the intended `jndi-name`
Blank, conflicting, or cross-scope mapping	Correct the complete effective chain	Application, module, and EJB identities
Direct global name/JNDI selection	Select a declared local alias	Repository `dataStore` and declaration
No locally targeted matching resource	Correct the destination JNDI or targets	Resource on every executing server
Duplicate matching JNDI bindings	Make the selected binding unique	One valid matching global descriptor
Sole visible resource used as fallback	Explicitly bind the resource. For unnamed selection, configure the required default	Exactly one bound eligible default
Repositories select different global identities	Use one bound global identity or separate deployments	All repositories using this integration path
Unsupported provider, type, or entity shape	Use the supported release contract	Provider/type configuration and programming book entity matrix

Deployment fails closed rather than choosing an arbitrary resource. Include the affected alias and scope in diagnostics, without credentials. Use approved generated message identifiers when available. The conditions above do not assign new message IDs.

The one-global-identity restriction applies to repositories using the WebLogic NoSQL system resource path. It does not impose a one-persistence-unit rule on Jakarta Persistence applications.