|Oracle® Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1)
Part Number B31974-05
This chapter describes how to package certain ADF components into the ADF Library for reuse in applications. Reusable ADF components are application modules, business components (entity objects, view objects, associations), data controls, task flows, page templates, and declarative components.
This chapter includes the following sections:
In the course of application development, certain components will often be used more than once. Whether the reuse happens within the same application, or across different applications, it is often advantageous to package these reusable components into a library that can be shared between different developers, across different teams, and even across departments within an organization.
In the world of Java object-oriented programming, reusing classes and objects is just standard procedure. With the introduction of the model-view-controller (MVC) architecture, applications can be further modularized into separate model, view, and controller layers. By separating the data (model and business services layers) from the presentation (view and controller layers), changes to any one layer do not affect the integrity of the other layers. You can change business logic without having to change the UI, or redesign the web pages or front end without having to recode domain logic.
Oracle ADF and JDeveloper support the MVC design pattern. When you create an application in JDeveloper, you can choose many application templates that automatically set up model and view-controller projects. Because the different MVC layers are decoupled from each other, development can proceed on different projects in parallel and with a certain amount of independence.
ADF Library further extends this modularity of design by providing a convenient and practical way to create, deploy, and reuse high-level components. When you first design your application, you design it with component reusability in mind. If you created components that can be reused, you can package them into JAR files and add them to a reusable component repository. If you need a component, you may look into the repository for those components and then add them into your project or application.
For example, you can create an application module for a domain and package it to be used as the data model project in several different applications. Or, if your application will be consuming components, you may be able to load a page template component from a repository of ADF Library JARs to create common look and feel pages. Then you can put your page flow together by stringing together several task flow components pulled from the library.
An ADF Library JAR contains ADF components and does not and cannot contain other JARs. It should not be confused with JDeveloper library, Java EE library or Oracle WebLogic shared library.
Table 33-1 lists the reusable components supported by ADF.
Table 33-1 Oracle ADF Reusable Components
Any data control can be packaged into an ADF Library JAR. Some of the data controls supported by Oracle ADF include application modules, Enterprise JavaBeans, web services, URL services, JavaBeans, and placeholder data controls.
When you are using ADF Business Components and you generate an application module, an associated application module data control is also generated. When you package an application module data control, you also package up the Business Components associated with that application module. The relevant entity objects, view objects, and associations will be a part of the ADF Library JAR and available for reuse.
Business components are the entity objects, view objects, and associations used in the ADF Business Components data model project. You can package business components by themselves or together with an application module.
Task flows can be packaged into an ADF Library JAR for reuse.
ADF bounded task flows built using pages can be dropped onto pages. The drop will create a link to call the bounded task flow. A task flow call activity and control flow will automatically be added to the task flow, with the view activity referencing the page. If there is more than one existing task flow with a view activity referencing the page, it will prompt for the application developer to select the one to automatically add a task flow call activity and control flow. If you drop a bounded task flow that uses page fragments, JDeveloper adds a region to the page and binds it to the dropped task flow.
If an ADF task flow template was created in the same project as the task flow, the ADF task flow template will be included in the ADF Library JAR and will be reusable.
You can package a page template and its artifacts into an ADF Library JAR. If the template uses image files and they are included in a directory within your project, these files will also be available for the template during reuse.
You can create declarative components and package them for reuse. The tag libraries associated with the component will be included and loaded into the consuming project.
You can also package up projects that have several different reusable components if you expect that more than one component will be consumed. For example, you can create a project that has both an application module and a bounded task flow. When this ADF Library JAR file is consumed, the application will have both the application module and the task flow available for use. You can package multiple components into one JAR file, or you can package a single component into a JAR file. Oracle ADF and JDeveloper give you the option and flexibility to create reusable components that best suit you and your organization.
You create a reusable component by using JDeveloper to package and deploy the project that contains the components into a ADF Library JAR file. You use the components by adding that JAR to the consuming project. At design time, the JAR is added to the consuming project's class path and so is available for reuse. At runtime, the reused component runs from the JAR file by reference. For the procedure to add the JAR manually, see Section 33.3.2, "How to Add an ADF Library JAR into a Project Manually." For the procedure to add the JAR using the JDeveloper Resource Catalog, see Section 33.3.1, "How to Add an ADF Library JAR into a Project using the Resource Palette".
Before you proceed to create reusable components, you should review the guidelines for creating reusable components.
Creating and consuming reusable components should be included in the early design and architectural phases of software projects. You and your development team should consider which components are candidates for reuse, not only in the current applications but also for future applications and including those applications being developed in other departments.
You and your team should decide on the type of repository needed to store the library JARs, where to store them and how to access them. You should consider how to organize and group the library JARs in a structure that fits your organizational needs. You should also consider creating standardized naming conventions so that both creators and consumers of ADF Library JARs can readily identify the component functionality.
Tip:If, in the midst of development, you and your team find a module that would be a good candidate for reuse, you can use the extensive refactoring capabilities of JDeveloper to help eliminate possible naming conflicts and adhere to reusable component naming conventions.
When you create reusable components, you should try to create unique and relevant names for the application, project, application module, task flow, connection, or any other file or component. Do not accept the JDeveloper wizard default names such as Application, Project, ViewController, AppModule,
task-flow-defintion.xml, or Connection. You want to try to have unique names to avoid naming conflicts with other projects, components, or connections in the application. Naming conflicts could arise from components created in the consuming application and those loaded from other JAR files. Table 33-2 lists the objects that you may be required to rename.
Table 33-2 Example Unique and Relevant Names for Reusable Components
Various possibilities. For more information, see Section 18.104.22.168.1.
ADF Library JAR file
adflib<string or 3-digit random number>N
For more information, see Section 22.214.171.124.
Be aware that some components use the default package name of the project without allowing the name to be explicitly set. In this situation, you must take extra care to avoid package name collisions. You can set the package name in the application creation wizard and you should check the names in the Project Properties dialog afterwards. If you don't set the package name, it will default to a variant of the project name, typically with the first letter being lowercase. For example, a project with the name
Project1 will have a default package name of
project1. You should manually change the package name to a more unique name before you proceed to build the project.
Note:The basic package naming requirement is that ADF metadata registries (
.cpx, and so on) are generated based on the project's package name, and you should avoid metadata naming conflicts between projects that will be combined at runtime.
When you are creating a reusable component's web resources files, such as JSPs, HTMLs, and task flows, you should create them in their own relative directories. When the JAR is deployed into another application, there will be less chance for conflict between the reusable component's files and the consuming application's files.
Oftentimes, several modules in an application will connect to the same data source. You should standardize the connection name to the same data source to avoid confusion because there is only one namespace for connections across the application. This would require coordination with other developers, component producers, and component consumers. For example, if
module2 both have a connection to the same database, the connection name should be standardized to an agreed upon name, such as
ADF Library JARs (with connections) may be used in different applications with different connection requirements. ADF Library JAR producers should choose connection names that are at least representative of the connection source, if not the actual standardized connection name. Be aware that consumers of the JAR that was created with connections will be required to satisfy the connection requirements when they add the component to the application.
For example, for a database connection, choosing an endpoint host name is usually not appropriate. The most appropriate name is a complete representative for the schema. Acceptable names for connections are
oracle-scottdb. You should realize that if many reusable components use different names for the same logical connection, then the customer of the component will have to satisfy each one individually with duplicate information. The consumer will have to supply connection details for several different connection names, when in fact they all refer to the same instance.
If an application has both EJB projects and a web application project with data binding, you should check to see that the EJB component names are not in conflict with any other web application project component names. The EJB project components may have global scope because the project is automatically added to the global class path of all web projects in the application. Web application projects may mistakenly access a component with the same name in the EJB project rather than within its own project.
For example, if both an EJB project and a web-based project have a
test1.jspx page, when the web-based project is run, it may try to run the EJB project
At runtime, JDeveloper detects if there are EJB projects and web application projects with data binding in the same application. If there are both types in the application, when the project is run and the server starts up, a warning message will appear in the Log window.
Before you package the project, you must create a deployment profile with the name and path for the JAR file. You should choose a name that follows you and your development team's naming convention and that is descriptive of the function of the component. You should realize that the consuming project may also include other JAR files from other software authors.
For example, if the component is a task flow for self-service paying, you might name it
mycompany.hcm.pay.selfservice.taskflows.jar. Other examples are
If you do not enter a name, JDeveloper will present a default name with the following format:
identifier is created with the following order of precedence:
Name of the project, other than
Name of the application, other than
A random three-digit number.
n is a number that starts with 1 and increments by 1 for each iteration of the profile.
For example, if the project name were
StoreFrontService, the profile name would be
adflibStoreFrontService1. If the project name were
Model, JDeveloper would reject this name and move to the second order of precedence, application name. If the application name were
FusionOrderDemoShared, then the project name would be
adflibFusionOrderDemoShared1. If neither the model nor the application name is usable, then a random three-digit number would be used instead, for example,
When you are creating reusable components, you should eliminate any projects that are not relevant to the reusable component. For example, if you want to create a reusable application module, you would need a data model project, but you would not need a view-controller project. In this instance, if you had created an application with both a data model and a view-controller project, you could delete the view-controller project. Of course, you should rename the default name
Model to something more relevant, such as
StoreFrontService. Similarly, if you are creating a reusable task flow that is not databound, you can delete any data model project from the application.
If you know the technology scope of your consuming projects, you can design your component with technologies that will be compatible. For example, if the consuming application uses only standard JSF Faces, then it may not be compatible with a declarative component that is built with ADF Faces.
When you create your application, you can define the technology scope using the Create Application Wizard by selecting from the application template.
After the project has been created, you can define the technology using the Technology Scope page of the Project Properties dialog.
If you are using the file system to store your ADF Library JARs, you should select file system locations that can function as repositories. You may want to put groups of JARs into a common directory folder, for example,
C:\ADF11\jdev\DevTeamADFRepository. If your team or organization plans to share ADF Library JARs, you should consider setting up network accessible repository folders, directories, or services. The Resource Palette has provisions to connect to different repository sources and make multiple connections. For more information about accessing ADF Library JARs using the Resource Palette, see Section 33.1.2, "Using the Resource Palette."
If the project you are packaging into an ADF Library JAR includes a connection, that information can be included in the JAR and may be available to the consuming project. Oracle ADF uses connection architecture which defines a connection as two parts, the connection name and the connection details (or endpoint definition). JDeveloper will present the producer of the JAR the option to package the connection name only or to include connection details with the connection name.
If a connection is present in the project, the packaged ADF Library JAR will contain a
jar-connections.xml file and a
jar-adf-config.xml file. They will be added to the META-INF directory. The
jar-connections.xml file contains the connection name and other relevant connection information. The
jar-adf-config.xml file stores the information about the credentials used for the connections. If connection credentials were also specified, then a
jar-credential-jazn-data.xml will also be included for the credential store. You can select the individual connections or connection types that you want to be packaged with the ADF Library JAR when you create the ADF Library JAR deployment profile. You make connection selections in the Create or Edit ADF Library Deployment Profile Properties dialog Connections page as described in Section 33.2.1, "How to Package a Component into an ADF Library JAR."
When an ADF Library JAR is being added to a project, JDeveloper checks for conflicts between the application's connections and the JAR's connections. A dialog will be presented to allow you to decide whether to proceed with adding the JAR to the project. Connections defined in the ADF Library JAR may be added to the consuming project, depending on the following conditions:
If the connection defined in the JAR is fully configured and there are no connection name conflicts with the consuming project, a new connection will be added.
If the connection defined in the JAR is partially configured, a new connection will be added to the consuming project but it must be configured before use. Connection dialogs may appear to allow the user to enter connection information. This partially configured connection may be indicated by an incomplete icon.
If the connection defined in the JAR has the same name as the application's connection, it will not be added to the project. The application's existing connection will be used.
If the connection defined in the JAR has the same name as the application's connection but is of different type, the JAR's connection will not be added to the project. For example, if a database connection in the JAR and a URL connection in the application have the same name, the database connection will not be added to the application.
For instructions on how to add an ADF Library to a project that includes connections, see Section 33.3.1, "How to Add an ADF Library JAR into a Project using the Resource Palette."
ADF Library JARs can be packaged, deployed, discovered, and consumed like any other Oracle Library component. Creating an ADF Library JAR is the action of packaging all the artifacts (and additional control files) of a project into a JAR. Consuming a reusable component from an ADF Library JAR is the action of loading that ADF Library JAR into the project's set of libraries.
However, the easiest way to manage and use ADF Library JAR components is by using JDeveloper's Resource Palette. With the Resource Palette, developers who want to consume reusable components can easily find and discover available components and add them to their projects. The Resource Palette provides search and browse functions across different data management systems to locate the component. It provides multiple connections to access different sources. It has a structure tree view for displaying different connections and the ADF Library JAR component types. Figure 33-1 shows the Resource Palette window with three file system connections,
StoreFront. In this example,
StoreFront contains the ADF Library component,
The Resource Palette tree structure displays each JAR as subcategories. Separate nodes are created for each type of reusable component. For example, application modules are under the Data Controls node, and task flows are under the ADF Task Flows node.
The tree structure for the ADF Library JAR lists any connection information under a Library Connections node and lists all the producing project's extension libraries under the Library Dependencies node.
An ADF project usually includes a list of extension libraries that it needs to run. These libraries are loaded in the class path of the project. You can view a project's dependent libraries by selecting the Libraries and Classpath node of the Project Properties dialog. Some of the libraries that may appear are JSP Runtime, ADF Page Flow Runtime, Connection Manager, and Oracle JDBC.
When a project is packaged into an ADF Library JAR, its extension libraries are packaged with it. And when an ADF Library JAR is being consumed by another project, JDeveloper automatically resolves any extension library conflicts between them. During the consuming process, JDeveloper checks to see whether the consuming project already has the extension libraries of the ADF Library JAR in its class path and loads only those libraries that it does not have. For example, if JSP Runtime already exists in the consuming project, it will not be loaded again if the ADF Library JAR also includes it. The consuming project's extension libraries will be a union of its own libraries and the libraries in the ADF Library JAR.
If the project you want to package into an ADF Library has a dependent project, you can include the dependent project's extension libraries directly in the JAR or, if the dependent project has a deployment profile, you can add the dependent project's JAR to the ADF Library. For more information about setting up the deployment process, see Section 33.2.1, "How to Package a Component into an ADF Library JAR."
For example, project
View is being packaged into ADF Library
adflibView1.jar. It has a dependency on the
Model project. For project
Model project is a dependent project with the deployment profile option (
adflibmodel1) selected, as shown in Figure 33-2.
When the deployment profile is selected, the dependent project's JAR file will be added to the ADF Library JAR. As a result, the extension libraries of the dependent project will also be made available to any consuming project. In Figure 33-3, the ADF Library being packaged,
adflibView1.jar, includes the dependent
adflibModel.jar as listed under the Library Dependencies node.
When you select
adflibView1.jar in the Resource Palette and choose Add to Project from the context menu, both
adflibModel.jar will be added to the consuming project's class path.
Figure 33-4 Class path of Consuming Project Showing ADF Library JAR and Dependent Project Library JAR
Alternately, you can include the dependent project's artifacts and extension libraries directly into the ADF Library JAR.
For example, project
View can also be packaged into ADF Library
adflibView2.jar. It also has a dependency on the
Model project. But in this second deployment profile, the
Model project is a dependent project with the Build Output option selected (as opposed to the deployment profile (
adflibmodel1) being selected), as shown in Figure 33-5.
When Build Output is selected, the dependent project's classes and extension libraries will be added directly to the ADF Library JAR. Figure 33-6 shows the ADF Library
adflibView2.jar, which includes artifacts of the
Model project and its extension libraries. Note that the extension libraries under the
adflibView2.jar Library Dependencies node are the same as the combined extension libraries under the
adflibModel.jar shown in Figure 33-3.
How you decide to package the dependent project depends on how you intend the ADF Library to be used. Including the dependent project as a JAR may be advantageous when the dependent project is itself a reusable component, or when it is a dependent project for several projects that will be packaged into an ADF Library JAR. In the example, the dependent project
Model may be a dependent project for several view projects. On the other hand, packaging the dependent project as Build Output is straightforward and eliminates the need for multiple JARs.
Note:If you are creating an ADF Library JAR that is included in a JDeveloper extension library, you should include the additional manifest
extension_library_nameentry in the JAR. When you use Add to Project from the Resource Palette to add a ADF Library JAR that has a
JDevLibrarymanifest entry, the JDeveloper extension library containing this JAR will be added instead of the ADF Library JAR itself.
Once you have decided that a certain component or components can be reused, create an application and a project to develop that component. Follow the guidelines in Section 33.1.1, "Creating Reusable Components" to name your application, project, package, and other objects and files. A project corresponds to one ADF Library JAR. If you create multiple projects and want to reuse components from each of the projects, you may need to create an ADF Library JAR for each project. In other situations, you may be able to involve multiple components under one project to create a single ADF Library JAR. For example, you may be able to create application modules, business components (entity object, view objects, associations), task flows, and page templates all under one project and create one ADF Library JAR.
Creating an ADF Library JAR involves compiling the project and validating the components, creating a resource service file, control files, an
adflibREADME.txt, and adding the relevant project files into a JAR. For more information about the ADF Library JAR, see Section 33.2.2, "What Happens When You Package a Project to an ADF Library JAR."
If you are packaging a component that itself uses another ADF Library component, the final consuming project must have both ADF Library JARs added to the project. For example, say you created a reusable task flow that contains tables dropped from a data control in another ADF Library JAR. When you add the task flow from an ADF Library JAR into a consuming project, that project will also require the data control ADF Library JAR.
If you are packaging a component that has dependent JARs, such as third-party JARs, you have two options:
If the consuming environment has control over the placement of JARs, you can place the ADF Library JAR and its dependent JARs in a JDeveloper Extension Library. The advantage of using a JDeveloper Extension Library is that it does not clutter the consuming project with specific references to the dependent JARs.
If using JDeveloper Extension Library is not possible, you can place the dependent JARs in the same location as the ADF Library JAR and include a manifest classpath entry for each dependent JAR.
To package up a reusable component, you first create a deployment profile that specifies the archive type, the name of the JAR file, and the directory path where the JAR will be created. Then you deploy the project using the deployment profile.
Before you begin:
You should already created a project and determine whether it has dependent projects and JAR that need to be packaged.
In the Application Navigator, double-click the project that contains the component you want to make reusable.
In the Project Properties dialog's left pane, select Deployment and then click New.
In the Create Deployment Profile dialog, select ADF Library JAR file for archive type, enter a name for the deployment profile, and click OK.
In the Project Properties dialog, select the deployment profile and click Edit.
In the Edit ADF Library JAR Deployment Profile Properties dialog, select the Library Dependencies node, as shown in Figure 33-8.
The Library Dependencies pane shows a list of dependent projects for the project being packaged. You can add the dependent project's build output directly into the packaging project's library, or you can add selected deployment profile archives to the class path.
To add dependent projects, click the Edit icon to bring up the Edit Dependencies dialog, as shown in Figure 33-9.
If you select Build Output, the dependent project's extension libraries will be added directly to the ADF Library JAR. If you select deployment profile, the dependent project's JAR file (which includes its own extension libraries) will be added to the ADF Library JAR. For more information about library dependencies, see Section 33.1.3, "Extension Libraries."
In this example, the
OrderBookingService project can be set as a dependency only as Build Output. However, the
StoreFrontUI project can be set as a dependency either as Build Output, or as a deployment profile (
For each dependent project, select the Build Output node for the project or select the dependent profile and click OK.
In the Edit ADF Library JAR Deployment Profile Properties dialog, select the Connections node, as shown in Figure 33-10.
You can select:
Connection Details (excluding secure content): If the project has a connection, select this checkbox if you want to add any available connection details in addition to the connection name. For more information, see Section 126.96.36.199, "Including Connections Within Reusable Components."
Connection Name Only: Select this checkbox if you want to add the connection name without any connection details such as security.
Note:The connection options available depends on the JDeveloper role. Connection Details (excluding secure content) and Connection Name Only are the selections available for the Default Role. If your JDeveloper is set to a different role, you may have different options and defaults.
In the Applications Connections tree structure, select the checkbox for the level of connection you want to include.
In the Edit ADF Library JAR Deployment Profile Properties dialog JAR Options node, as shown in Figure 33-11, verify the default directory path or enter a new path to store your ADF Library JAR file.
If the ADF Library JAR is to be included in a JDeveloper extension library, create a text file with a
extension_library_name entry and place the file in the project root directory. Click Add to locate and merge that file into the
When you create your manifest text file, make sure the
JDevLibrary entry starts in column 1 with a space after the colon, and that there is a blank line at the end of the file.
In the Edit ADF Library JAR Deployment Profile Properties dialog ADF Validation node, select:
Ignore Errors: Select this option to create the JAR file even when validation fails. This is the default option.
Stop Processing: Select this option to stop processing when validation fails.
Click OK to finish setting up the deployment profile.
In the Application Navigator, right-click the project and choose Deploy > deployment, where deployment is the name of the deployment profile.
In the Deploy dialog Deployment Action page, click Next and then click Finish.
JDeveloper will create the ADF Library JAR in the directory specified in Step 7. You can check that directory to see whether the JAR was created.
When you deploy the library JAR, JDeveloper packages up all the necessary artifacts, adds the appropriate control files, generates the JAR file, and places it in the directory specified in the deployment profile. During deployment, you will see compilation messages in the Log window.
When you deploy a project into an ADF Library JAR, JDeveloper performs the following actions:
Package the HTML root directory artifacts into the JAR. When the JAR is added to the consuming project, JDeveloper will make the reusable component's
public_html resources available by adding it to the class path.
adfm.xml file to the JAR. If there are multiple
META-INF/adfm.xml files in the workspace, only the
adfm.xml in the project being deployed is added. JDeveloper modifies this file to include relevant content from any dependent project's
Add a service resources file,
oracle.adf.common.services.ResourceService.sva, into the
META-INF directory of the JAR. The addition of this file differentiates an ADF Library JAR file from standard JAR files. This file defines the service strategies of the JAR and allows the Resource Palette to properly discover and display the contents of the JAR.
Manifest.mf file to the JAR. The
Manifest.mf file is used to specify dependencies between JAR files, and whether to copy and include the contents of a JAR file or to reference it. JDeveloper will create a default manifest file. For example:
jar-connections.xml file to the JAR for components that require a connection and that use the connections architecture. Note that in the consuming application, connection information in configuration files that are defined in the class path and accessible at runtime may be merged together. If the same connection is named multiple times in the class path, the connection in the main application will be given priority.
Different types of reusable components have different artifact files and different entries in the service resource file.
For application modules, JDeveloper adds three control files to the JAR:
Manifest.mf,and adfm.xml. The service resource file for an application module includes entries for the business components associated with the application module, as well as an entry for the application module data control.
jar-connections.xml file may appear for components that use the connection architecture and that contain connection information regarding the data source.
For data controls such as placeholder data controls, JDeveloper includes three control files in the JAR:
DataControl.dcx file. Data controls are used when the data source is not based on ADF Business Components, and so business components are not included in the JAR file, as is the case in an application module JAR file. The service resource file for a standard data control has an entry for the data control.
The JAR also includes the
Datacontrol.dcx file from the project to describe the data control type.
For task flows, JDeveloper includes three control files in the JAR:
task-flow-registry.xml. The service resource file for a task flow includes an entry that indicates that one or more task flows are in the JAR.
For page templates, JDeveloper includes two control files in the JAR:
If you have JAR files that can be reused by other projects, such as third-part JAR files, you can use JDeveloper to place them in an accessible location and create a library file (
.library) to designate them. The consumer can use JDeveloper to navigate to this location and add the JAR to the project.
An ADF Library JAR contains ADF components and does not and cannot contain other JARs.
Before you begin:
Place the JAR files in a accessible location for both the producer and the consumer of these JAR files. For example, the directory may be on a network drive where other shared files are located.
To place and access a JDeveloper LIbrary JAR:
From the main menu, choose Tools > Manage Libraries.
In the Manage Libraries dialog, click Load Dir.
In the Load Directory dialog, select the directory where the secondary JAR files are located.
In the Manage Libraries dialog, click New.
In the Create Library dialog, enter a library name and click Add Entry.
You have created a library file (with a
.library extension). You should place library files in source control systems.
In the Select Path Entry dialog, select the JARs you want to add and click Select.
In the Create Library dialog, be sure that the Deployed by Default option is set correctly for your JAR, click OK and click OK again.
In the JDeveloper of the consuming project.
From the main menu, choose Tools > Manage Libraries.
In the Manage Libraries dialog, click Load Dir.
In the Load Directory dialog, select the directory where the secondary JAR files are located and click OK. This should be the same location specified by the producer in step 3.
Right-click the project and select Project Properties.
In the Project Properties window, select Libraries and Classpath and click Add Library.
In the Add Library dialog, select the library, click OK and click OK again.
After ADF Library JARs are created, they must be distributed to the developers who will use these JARs. Distributing the ADF Library JARs may include putting the JARs into network file system to be searched, browsed, and discovered. It may include using other forms of data store or services to access and retrieve these JARs. Since ADF Library JARs are simply binary files, they can distributed like any other file such as ftp and email.
Once you have access to the ADF Library JARs, you can use JDeveloper to access them and add them to your consuming projects. Using the JDeveloper Resource Palette is the easiest and most efficient way. You can also use JDeveloper to manually add the JARs into the project by entering them into the class path.
When a project is packaged into an ADF Library JAR, it captures the list of dependent JARs the project needs for deployment and run time. This list is based on the project's dependent profiles and the information in the project's Libraries and Classpath with Deployed By Default selected. When the ADF Library JAR is added to the consuming project, this list of dependent JARs is placed in a library called ADF Library Dependencies. This is a locked library in the consuming project and its content will not be shown in the Data Control panel, Component Palette, or other places in JDeveloper. The library is maintained and updated as different ADF Library JARs are added and deleted from the project. If the dependencies changed, (for example, the producer project was rebuilt), then you can refresh the dependencies in the consuming project using a JDeveloper menu command.
Once reusable components have been added, how they are used depends on the type of component.
You can use the Resource Palette to search, discover, and add the ADF Library JAR to your project.
Before you begin:
You should already have an ADF Library JAR in a repository folder. If you do not already have a Resource Palette connection to this repository, you must know the location of this folder.
To add a component to the project using the Resource Palette:
From the View menu, choose Resource Palette.
In the Resource Palette, click the New icon, and then choose New Connection > File System.
In the Create File System Connection dialog, enter a name and the path of the folder that contains the JAR. For file path guidelines, see Section 188.8.131.52, "Selecting Paths and Folders."
The new ADF Library JAR appears under the connection name in the Resource Palette.
To examine each item in the JAR structure tree, use tooltips. The tooltip shows pertinent information such as the source of the selected item.
Figure 33-13 shows a Resource Palette with a tooltip message that shows package information for a business component.
To add the ADF Library JAR or one of its items to the project, right-click the item and choose Add to Project. In the confirmation dialog that appears, click Add Library, as shown in Figure 33-14.
If you had previously added that library JAR, you will get a Confirm Refresh ADF Library dialog asking you whether you want to refresh the library.
If the ADF Library JAR has changes to its dependencies, you can refresh the project with the new changes. From the Application Navigator, right-click the project and select Refresh ADF Library Dependencies in project.jpr.
For application modules and data controls, you have the option to drag and drop the application module or data control from the Resource Palette into the Data Controls panel.
Note:JDeveloper will load whichever ADF Library JAR extension libraries are not already in the consuming project. Extension libraries from the ADF Library's dependent JARs will also be checked and loaded if not already part of the consuming project. For more information, see Section 33.1.3, "Extension Libraries"
You can add an ADF Library JAR in the same way as you would other library JARs.
Before you begin:
You should already have an ADF Library JAR.
To add a component to a project manually:
In the Application Navigator, double-click the project to which the component is to be added.
In the Project Properties dialog, select the Libraries and Classpath node and then click Add Library.
In the Add Library dialog, click New.
In the Create Library dialog, select Project in the Location dropdown list and enter a name for the ADF Library. The preferable name is "ADF Library". Select Deploy by Default, and click Add Entry.
In the Select Path Entry dialog, enter or browse to the ADF Library JAR file and click Select.
The Create Library dialog reappears with the path of the JAR file filled in under the Class Path node. Click OK.
The Add Library dialog reappears with the ADF Library entry filled in under the Project node. Click OK.
The Project Properties dialog reappears with the JAR file added to the list of libraries. Click OK.
When you add an ADF Library JAR to a project, either by using the Resource Palette or by manually adding the JAR, an ADF Library definition is created in the project. The ADF Library JAR file will be added to the class path of the project. The project will access and consume the components in the JAR by reference.
By default, the ADF Library Deployed by Default option in the Create Library dialog is set to true. If this option is set, when the application or module is further archived or built into a WAR file, the contents of the ADF Library JAR will be copied to that archive or WAR file. If the Deploy by Default option is not set, then the JARs in the ADF Library must be loaded in some other way, such as by deploying them in a shared library.
Figure 33-16 shows the empty Data Controls panel for a consuming project before the ADF Library was added.
Figure 33-17 shows the
adflibStoreFrontService ADF Library being added to the consuming project.
Figure 33-18 shows several data controls from the ADF Library added to the Data Controls panel in the consuming project.
After adding the ADF Library JAR, you may notice some changes to some of the JDeveloper windows. These changes are different depending on the type of components being added. Table 33-3 lists the effects on several JDeveloper windows.
Table 33-3 JDeveloper Window After Adding an ADF Library
|Added Component||Data Controls Panel||Creation Wizards||Component Palette|
Data control appears.
Application module appears.
Entity objects available in view object creation wizard. View objects in JAR also available for use.
Task flows appear in Component Palette.
Page template available during JSF creation wizard.
Tag library appears in Component Palette. Declarative component appears in the list.
Although the procedure to add an ADF Library JAR to a project is standardized, the component type determines where it appears in JDeveloper and how it can be reused.
When you add a data control to a project, the data control appears in the Data Controls panel. If you are using the Resource Palette, you have the option of dragging and dropping the data control from the Resource Palette onto the Data Controls panel, and then dragging and dropping from the Data Controls panel onto the page.
When you add an application module to a project, the application module appears in the Data Controls panel. If you are using the Resource Palette, you have the option of dragging and dropping the application module item from the Resource Palette onto the Data Controls panel, and then dragging and dropping from the Data Controls panel onto the page.
Application modules are associated with business components. When the reusable application module was packaged, the JAR includes the business components used to create the application module. These components will be available for reuse.
Business components can also be packaged and reused. The entity objects, view objects, and associations can be packaged together and added to a consuming project. By default, packaged application modules will include the business components in the JAR, but business components can be reused by themselves without the accompanying application module.
One way to reuse business components is to create new view objects using the entity objects from an ADF Library JAR. When you add view objects using the wizard, the entity objects will become available within the wizard to support view object generation. For instructions on creating view objects, see Section 5.2.1, "How to Create an Entity-Based View Object." When the wizard presents a screen for entity objects used to create view objects, the entity objects from the ADF Library will be available in the shuttle window, as shown in Figure 33-19.
If the consuming project has the Initialize Project for Business Component option selected (in the Project Properties dialog Business Components page) before the ADF Library JAR is added, the business components within the JAR will automatically be made available to the project.
If you add the ADF Library JAR first, and then select Initialize Project for Business Component, JDeveloper will automatically load the business components.
Task flows added to a project will appear in the Component Palette when you are adding components to a JSF page. If you are using the Resource Palette, you can also drag and drop the task flow directly from the Resource Palette onto another task flow or page, as shown in Figure 33-20.
For more information about creating task flows, see Chapter 14, "Getting Started with ADF Task Flows."
When you add a page template to a project, the template will not be exposed in the Application Navigator. You will not have direct access to individual supporting files, such as image files. However, the template retains its access to its supporting files inside the JAR and is fully reusable within the project. When you apply the template, it will retain all the images that were loaded with the template.
The page template is exposed and accessible when you create a new JSF JSP page using the wizard. When the wizard presents you with the option to use a page template, the ADF Library template will appear in the dropdown list. For example, if you loaded a page template called
FODTemplate from an ADF Library, when you use the wizard to create a JSF JSP page,
FODTemplate will appear in the wizard, as shown in Figure 33-21. For information on how to use page templates and create a JSF JSP page, see Section 20.2, "Using Page Templates" and the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.
When you add a declarative component to a project, the JSP tag libraries that contain the component will be added to the project. The tag libraries will appear in the Component Palette, and the declarative components will be available for selection. For information about creating and using declarative components, see the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.
If you mix components created during application development with components imported from the ADF Library, you may be able to differentiate between them by using the tooltips feature of JDeveloper.
Move the cursor over an application module or data control and you will see the full path of the source. If you see the ADF Library JAR file in the path, that means the component source is the ADF Library.
After an ADF Library JAR has been added to a project and to the class path, it behaves like any other library file. During runtime, any component that uses the component in the ADF Library JAR will reference that object. The process is transparent and there is no need to distinguish between components that were developed for the project and those that are in ADF Library JARs. Figure 33-22 shows the ADF Library and the path to the JAR as defined for a project.
You can use the Resource Palette to remove an ADF Library JAR from a project, or you can manually remove the JAR using the Project Properties dialog. You can remove an ADF Library JAR only if the components in the project do not have any dependencies on the components in the ADF Library JAR.
When you remove a JAR, it will no longer be in the project class path and its components will no longer be available for use.
The Resource Palette allows you to remove previously added ADF Library JARs from a project using a simple command.
From the View menu, choose Resource Palette.
In the Application Navigator, select the project that has the ADF Library JAR you want to remove.
In the Resource Palette, locate the ADF Library JAR you want to remove from the current project.
Right-click the JAR and choose Remove from Project.
When you remove an ADF Library JAR manually, be sure to remove the correct library. Be aware of other libraries that are critical to the operation of the project.
To remove an ADF Library JAR from the project manually:
In the Application Navigator, double-click the project.
In the Project Properties dialog, select the Libraries and Classpath node.
In the Classpath Entries list, select ADF Library and click Edit.
In the Edit Library Definition dialog, select the ADF Library JAR you want to remove under the Class Path node, and click Remove.
Click OK to accept the deletion, and click OK again to exit the dialog.