Application bindings

Before an application that is installed on an application server can start, all enterprise bean (EJB) references and resource references that are defined in the application must be bound to the actual artifacts (enterprise beans or resources) defined in the application server.

In version 22.0.0.8 and later, documentation for application bindings is available on the Open Liberty website.

Application bindings and extensions provide ways to define application resources and control various application behaviors. Application bindings can apply to enterprise applications, web applications, or EJB applications.

Traditionally, these bindings and extensions are specified in XML files inside the application archive. For example, web application bindings can be defined in the ibm-web-bnd.xml file. In Liberty version 17.0.0.1 and later, bindings and extensions can be specified as part of the application configuration in the server.xml file.

Liberty supports the traditional method of defining the bindings and extensions as part of the application. If information is specified in both the server.xmlfile and the application, the two sources are merged to create the effective set of bindings or extensions.

Information that is specified in the server.xml file takes precedence over the same information that is specified in an application artifact. For example, if both the ibm-web-bnd.xml and the server.xml file specify a virtual host for a web application, the value that is specified in the server.xml file is used. If the information that is being specified can have multiple values, the values from the server.xml file are added to the values from the application. For example, if the ibm-application-bnd.xml file defines two security roles and the server.xml file defines one, all three security roles are used. If a security role that is defined in the server.xml file has the same name as a security role defined in the ibm-application-bnd.xml file, the role from the server.xml file overwrites the one from the application.

For bindings and extensions that apply to a specific module within an application, it might be necessary to specify a moduleName attribute in the configuration. This specification applies to information that would traditionally be specified in the ibm-web-ext.xml file, the ibm-web-bnd.xml file, the ibm-ejb-jar-bnd.xml, and the ibm-ejb-jar-ext.xml file. The module name attribute is the name of the module without a file extension. For example, for an enterprise application that is defined in the file stockPrices.ear that contains a web module in the archive stockDisplay.war, the following configuration would set the default error page for the web module:

<application location="stockPrices.ear">
   <web-ext moduleName="stockDisplay" default-error-page="error.html"/>
</application>

Similarly for an EJB application that is defined in the stockData.jar file, the following server.xml configuration would specify a data source binding:

<application location="stockPrices.ear">
   <ejb-jar-bnd moduleName="stockData">
	<session name="StockBean">				
		<data-source name="jdbc/stockDS" binding-name="stockDataSource"/>
 	</session>  
   </ejb-jar>
</application>

The module name parameter is not necessary if the application is in a stand-alone WAR or JAR file and defined in the server.xml file by using a webApplication or ejbApplication element. For example, if the stockDisplay.war file and the stockData.jar file from the previous example were stand-alone applications instead of modules for the stockPrices.ear application, the following configuration might be used:

<webApplication location="stockPrices.ear">
   <web-ext default-error-page="error.html"/>
</webApplication>

<ejbApplication location="stockPrices.jar">
   <ejb-jar-bnd>
	<session name="StockBean">				
		<data-source name="jdbc/stockDS" binding-name="stockDataSource"/>
 	</session>  
   </ejb-jar>
</ejbApplication>

Some elements that were specified in the bindings and extensions files are not in use by the Liberty runtime. For example, in the web application extensions the value of the reload interval attribute is ignored because in Liberty reload behavior is controlled by the applicationMonitor configuration. No errors result from specifying these elements in the server.xml configuration. However, this might result in unrecognized element warnings when you edit the configuration in the WebSphere Developer Tools.

In some cases, configuration that was specified in the bindings and extensions files as a child element must be specified as an attribute in the server.xml file. This affects cases where the child element only had one possible attribute value, such as shared-session-context in the application extensions file or context-root in the web extensions file. In each case, the child element name in the extensions file becomes an attribute name in server.xml and the value of the child element's single attribute becomes the attribute value in server.xml. For example, the configuration of context-root in the web extensions file might look like this:

<web-ext>
   <context-root uri="stockPrices"/>
</web-ext>

The corresponding configuration in server.xml would look like this:

<web-ext context-root="stockPrices"/>

For the full list of bindings and extensions that can be specified in the server.xml file, see configuration elements in the server.xml file.

The following example specifies a resource reference for a managed bean inside an EJB application.

<ejbApplication location="someBean.jar">
<managed-bean-bnd>
	<managed-bean class="com.ibm.MyBean">
		<resource-ref name="jdbc/myBinding" binding-name="jdbc/TestDataSource" />
	</managed-bean>
</managed-bean-bnd>
</ejbApplication>

The following configuration sets the shared session context attribute for an application to false:

<application location="myApplication.ear">
	<application-ext shared-session-context="false" />
</application>

The following configuration sets the virtual host for a web application:

<application location="myApplication.ear">
	<web-bnd moduleName="myWebModule">
		<virtual-host name="default_host" />
	</web-bnd>
</application>