Fusion Middleware Documentation
Advanced Search


Developing Fusion Web Applications with Oracle Application Development Framework
Close Window

Table of Contents

Show All | Collapse

44 Reusing Application Components

This chapter describes how to package certain Oracle ADF components into the ADF Library for reuse in Fusion web 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:

44.1 About Reusable Components

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), you ensure that 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 data model and user interface 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 the JDeveloper library, Java EE library, or Oracle WebLogic shared library.

Table 44-1 lists the reusable components supported by ADF.

Table 44-1 Oracle ADF Reusable Components

Reusable Component Description

Data control

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.

Application module

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 ADF 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

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 and taskflow templates

Task flows can be packaged into an ADF Library JAR for reuse.

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.

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 you to select the one to automatically add a task flow call activity and control 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.

Page templates

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.

Declarative components

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 44.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 44.3.1, "How to Add an ADF Library JAR into a Project using the Resources Window."

Before you proceed to create reusable components, you should review the guidelines for creating reusable components.

44.1.1 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.

44.1.1.1 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 44-2 lists the objects that you may be required to rename.

Table 44-2 Example Unique and Relevant Names for Reusable Components

Type JDeveloper Default Example

Application

Application

SummitADF

Project

Model

ViewController

Project

BackOfficService

OrderTrackingUI

Package

Various possibilities. For more information, see Section 44.1.1.1.1.

oracle.summit

Application module

AppModule

SummitAppModuleDataControl

Connection

Connection1

summit_adf

Task flow

task-flow-defintion.xml

customer-task-flow-definition.xml

Page template

templateDef.jspx

SummitTemplate.jspx

Declarative Component

componentDef

componentDef.jspx

SummitsuperwidgetDef

SummitsuperwidgetDef.jspx

ADF Library JAR file

adflib<string or 3-digit random number>N

For more information, see Section 44.1.1.2.

SummitADF_Model_adflibSummitADF1


44.1.1.1.1 Naming Considerations for Packages

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 (.dcx,.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 resource 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.

Note:

You can override the staleness period setting of 364 days for all static web application resources in ADF Libraries by adding initialization parameters to the web.xml file. For more information, see Appendix A, "web.xml."

44.1.1.1.2 Naming Considerations for Connections

Often, 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 customers and suppliers both have a connection to the same database, the connection name should be standardized to an agreed upon name, such as orders_db.

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 example names for connections are oracle-appsdb and oracle-customersdb. You should realize that if many reusable components use different names for the same logical connection, then the consumer 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.

44.1.1.1.3 Naming Considerations for Applications with EJB Projects

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. The web application project 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 test1.jspx page.

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.

44.1.1.2 The Naming Process for the ADF Library JAR Deployment Profile

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 oracle.apps.hcm.pay.model.jar and mycompany.hcm.pay.model.overrides.jar.

When you create the deployment profile, JDeveloper will present a default name with the following format:

adflibidentifierN

Where identifier is random number up to three-digits and N is a number that starts with 1 and increments by 1 for each iteration of the profile.

For example, the default name for a profile may be adflib7491(random number is 749 and suffix is 1). The default name for the another profile may be adflib51 (random number is 5 and suffix is 1).

You can change this default name to a name of your choice.

44.1.1.3 Keeping the Relevant Project

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 user interface project. In this instance, if you had created an application with both a data model and a user interface project, you could delete the user interface project. Of course, you should rename the default name Model to something more relevant, such as BackOfficeService. Similarly, if you are creating a reusable task flow that is not databound, you can delete any data model project from the application.

44.1.1.4 Selecting the Relevant Feature

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 features using the Create Application Wizard by selecting from the application template.

After the project has been created, you can define the technology using the Features page of the Project Properties dialog.

44.1.1.5 Selecting Paths and Folders

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:\ADF\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 Resources window has provisions to connect to different repository sources and make multiple connections. For more information about accessing ADF Library JARs using the Resources window, see Section 44.1.4.2, "Using the Resources Window."

44.1.1.6 Including Connections Within Reusable Components

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 44.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 44.3.1, "How to Add an ADF Library JAR into a Project using the Resources Window."

Note:

In the process of adding the ADF Library to a project, you will see one message displayed in the Log window for each connection defined in the JAR. The messages indicate the merge action taking place in the project.

44.1.2 Reusable ADF Components Use Cases and Examples

Packaging projects into ADF Library JARs allows components to be reused multiple times in the same or in different applications. Different development teams can create and consume projects and create libraries of reusable modules. ADF Library JARs support the M-V-C design pattern. You can create ADF Libraries and access them using drag and drop from the Resources window.

For instance, you can package up an application module into an ADF Library JAR and place it in a public folder for other team to use. Different implementation teams may access that JAR to create their applications. They may use the application module to create different pages for their use instead on having to create their own application modules. When there is a change in the model, the original developer can repackage the application module and republish the ADF Library JAR. The other implementation teams can update their application using the updated ADF Library.

44.1.3 Additional Functionality for Reusable ADF Components

You may find it helpful to understand other ADF features before you work with reusable ADF components. Following are links to other functionality that may be of interest.

44.1.4 Common Functionality of Reusable ADF Components

When you package or consume an ADF Library JAR, you also include and consume the extension libraries that are associated with the project. When you consume an ADF Library, you can use the Resources window.

44.1.4.1 Using Extension Libraries

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 44.2.1, "How to Package a Component into an ADF Library JAR."

For example, suppose that project View is being packaged into ADF Library adflibView1.jar and that has a dependency on the Model project. For project View, the Model project is a dependent project with the deployment profile option (adflibmodel1) selected, as shown in Figure 44-1.

Figure 44-1 Edit Dependencies Dialog with Deployment Profile Option

Edit Dependencies deployment profile selection

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 44-2, the ADF Library being packaged, adflibView1.jar, includes the dependent adflibModel.jar as listed under the Library Dependencies node.

Figure 44-2 Resources Window Showing adflibView1.jar and adflibModel.jar Extension Libraries

Library Dependencies for embedded JARs.

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 44-3.

Figure 44-3 Edit Dependencies Dialog Used to Built adflibview2.jar

Edit Dependencies dialog Model dependent project

When Build Output is selected, the dependent project's classes and extension libraries will be added directly to the ADF Library JAR. Figure 44-4 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 adflibView1.jar and adflibModel.jar shown in Figure 44-2.

Figure 44-4 Resources Window Showing adflibView2.jar Extension Libraries

Resource Palette showing ADF Library structure.

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 JDevLibrary: extension_library_name entry in the JAR. When you use Add to Project from the Resources window to add a ADF Library JAR that has a JDevLibrary manifest entry, the JDeveloper extension library containing this JAR will be added instead of the ADF Library JAR itself.

44.1.4.2 Using the Resources Window

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 Resources window. With the Resources window, developers who want to consume reusable components can easily find and discover available components and add them to their projects. The Resources window 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 44-5 shows the Resources window with several file system connections.

The Resources window 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.

Figure 44-5 Resources Window Showing ADF Library Structure

Resource Palette ADF Libraries.

44.2 Packaging a Reusable ADF Component into an ADF Library

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 44.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 44.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.

44.2.1 How to Package a Component into an ADF Library 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:

It may be helpful to have an understanding of the options that are available to you when you package an ADF component. For more information, see Section 44.2, "Packaging a Reusable ADF Component into an ADF Library."

You may also find it helpful to understand functionality that can be used with packaging an ADF component. For more information, see Section 44.1.3, "Additional Functionality for Reusable ADF Components."

You will need to complete this task:

Create a project and determine whether it has dependent projects and JAR that need to be packaged. For more information, see Section 44.2, "Packaging a Reusable ADF Component into an ADF Library."

To package and deploy a project into the ADF Library JAR:

  1. In the Applications window, double-click the project that contains the component you want to make reusable.

  2. In the Project Properties dialog, select Deployment and then click New.

  3. In the Create Deployment Profile dialog, select ADF Library JAR file for Profile Type, enter a name or accept the default name for Deployment Profile Name, and click OK.

    Figure 44-6 Create Deployment Profile Dialog with Default Name

    Create deployment profile dialog
  4. In the Project Properties dialog, select the deployment profile and click Edit.

  5. In the Edit ADF Library JAR Deployment Profile Properties dialog, select the Library Dependencies node, as shown in Figure 44-7.

    Figure 44-7 ADF Library JAR Deployment Profile Properties Dialog

    ADF Deployment Profile Properties dialog.

    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.

    1. To add dependent projects, click the Edit icon to bring up the Edit Dependencies dialog, as shown in Figure 44-8.

      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 44.1.4.1, "Using Extension Libraries."

      In this example, the Model project can be set as a dependency only as Build Output. However, the ViewController project can be set as a dependency either as Build Output, or as a deployment profile (SummitADF_ViewController_webapp).

      Figure 44-8 ADF Library Deployment Edit Dependencies Dialog

      ADF Deployment Profile Edit Dependencies dialog.
    2. For each dependent project, select the Build Output node for the project or select the dependent profile and click OK.

  6. In the Edit ADF Library JAR Deployment Profile Properties dialog, select the Connections node, as shown in Figure 44-9.

    You can select:

    • Connection Details (excluding secure content): If the project has a connection, select this checkbox if you want to include any available connection details in addition to the connection name. Connection details include hostname, port number, sid, driver type, and user name. For more information, see Section 44.1.1.6, "Including Connections Within Reusable Components."

    • Connection Name Only: Select this checkbox if you want to add the connection name without any connection details.

    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 Studio Developer 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.

    Figure 44-9 Connections Page of the Edit ADF Library JAR Deployment Profile Properties Dialog

    ADF Deployment Profile Connections tab.
  7. Select the JAR Options node, as shown in Figure 44-10, 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 JDevLibrary: extension_library_name entry and place the file in the project root directory. Click Add to locate and merge that file into the Manifest.mf file.

    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.

    Figure 44-10 ADF Library JAR Deployment Profile Properties Dialog JAR Option

    ADF Deployment Profile JAR Option
  8. Select the ADF Validation node.

    You can select:

    • Ignore Errors: To create the JAR file even when validation fails. This is the default option.

    • Stop Processing: To stop processing when validation fails.

    Figure 44-11 ADF Library JAR Deployment Profile Properties Dialog ADF Validation

    ADF Deployment Profile ADF Validation tab
  9. Click OK to finish setting up the deployment profile.

  10. In the Applications window, right-click the project and choose Deploy > deployment, where deployment is the name of the deployment profile.

  11. 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.

44.2.2 What Happens When You Package a Project to an ADF Library JAR

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.

  • Add the 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 adfm.xml file.

  • 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 Resources window to properly discover and display the contents of the JAR.

  • Add a Manifest.mf file to the JAR. The Manifest.mf file is used to specify dependencies between JAR files, and to determine whether to copy and include the contents of a JAR file or to reference it. JDeveloper will create a default manifest file. For example:

    Manifest-Version: 1.0
    
  • Adds a 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.

44.2.2.1 Application Modules Files Packaged into a JAR

For application modules, JDeveloper adds these control files to the JAR: oracle.adf.common.services.ResourceService.sva, Manifest.mf, adfm.xml, and the business components .jpx file. 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.

The jar-connections.xml file may appear for components that use the connection architecture and that contain connection information regarding the data source.

44.2.2.2 Data Controls Files Packaged into a JAR

For data controls such as placeholder data controls, JDeveloper includes three control files in the JAR: oracle.adf.common.services.ResourceService.sva, Manifest.mf, and 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.

44.2.2.3 Task Flows Files Packaged into a JAR

For task flows, JDeveloper includes three control files in the JAR: oracle.adf.common.services.ResourceService.sva, Manifest.mf, and 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.

44.2.2.4 Page Templates Files Packaged into a JAR

For page templates, JDeveloper includes two control files in the JAR: oracle.adf.common.services.ResourceService.sva and Manifest.mf.

44.2.2.5 Declarative Components Files Packaged into a JAR

For declarative components, JDeveloper includes two control files in the JAR: oracle.adf.common.services.ResourceService.sva and Manifest.mf.

44.2.3 How to Place and Access JDeveloper JAR Files

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:

It may be helpful to have an understanding of the options that are available to you when you package an ADF component. For more information, see Section 44.2, "Packaging a Reusable ADF Component into an ADF Library."

You may also find it helpful to understand functionality that can be used with packaging an ADF component. For more information, see Section 44.1.3, "Additional Functionality for Reusable ADF Components."

You will need to complete this task:

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. For more information, see Section 44.2, "Packaging a Reusable ADF Component into an ADF Library."

To place and access a JDeveloper LIbrary JAR:

  1. From the main menu, choose Tools > Manage Libraries.

  2. In the Manage Libraries dialog, click Load Dir.

  3. In the Load Directory dialog, select the directory where the secondary JAR files are located.

  4. In the Manage Libraries dialog, click New.

  5. 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.

  6. In the Select Path Entry dialog, select the JARs you want to add and click OK.

  7. In the Create Library dialog, be sure that the Deployed by Default option is set correctly for your JAR, click OK and then click OK again.

  8. In the consuming project.

    1. From the main menu, choose Tools > Manage Libraries.

    2. In the Manage Libraries dialog, click Load Dir.

    3. In the Load Directory dialog, select the directory where the secondary JAR files are located and click Select. This should be the same location specified in Step 3.

    4. Right-click the project and select Project Properties.

    5. In the Project Properties window, select Libraries and Classpath and click Add Library.

    6. In the Add Library dialog, select the library, click OK and then click OK again.

44.3 Adding ADF Library Components into Projects

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 a 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 Resources window 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 runtime. 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 Controls panel, Components window, 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 have 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.

44.3.1 How to Add an ADF Library JAR into a Project using the Resources Window

You can use the Resources window to search, discover, and add the ADF Library JAR to your project.

Before you begin:

It may be helpful to have an understanding of the options that are available to you when you package an ADF component. For more information, see Section 44.3, "Adding ADF Library Components into Projects."

You may also find it helpful to understand functionality that can be used with packaging an ADF component. For more information, see Section 44.1.3, "Additional Functionality for Reusable ADF Components."

You will need to complete this task:

Create an ADF Library JAR in a repository folder. If you do not already have a Resources window connection to this repository, you must know the location of this folder. For more information, see Section 44.3, "Adding ADF Library Components into Projects."

To add a component to the project using the Resources Window:

  1. From the main menu, choose Window > Resources.

  2. In the Resources window, click the New icon, and then choose IDE Connections > File System.

  3. 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 44.1.1.5, "Selecting Paths and Folders."

  4. Click OK.

    The new ADF Library JAR appears under the connection name in the Resources window.

  5. 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 44-12 shows a Resources window with a tooltip message that shows package information for a business component.

    Figure 44-12 Tooltip Message for a Connection in the Resources Window

    Resource Palette for ADF Library and tool tip.
  6. 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 44-13.

    Figure 44-13 Confirm Add ADF Library Dialog

    Confirm ADF Library dialog.

    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.

  7. If the ADF Library JAR has changes to its dependencies, you can refresh the project with the new changes. From the Applications window, 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 Resources window 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 44.1.4.1, "Using Extension Libraries"

44.3.2 How to Add an ADF Library JAR into a Project Manually

You can add an ADF Library JAR in the same way as you would other library JARs.

Before you begin:

It may be helpful to have an understanding of the options that are available to you when you package an ADF component. For more information, see Section 44.3, "Adding ADF Library Components into Projects."

You may also find it helpful to understand functionality that can be used with packaging an ADF component. For more information, see Section 44.1.3, "Additional Functionality for Reusable ADF Components."

You will need to complete this task:

Create an ADF Library JAR. For more information, see Section 44.3, "Adding ADF Library Components into Projects."

To add a component to a project manually:

  1. In the Applications window, double-click the project to which the component is to be added.

  2. In the Project Properties dialog, select the Libraries and Classpath node and then click Add Library.

  3. In the Add Library dialog, click New.

  4. In the Create Library dialog, in the Location dropdown list, select Project and enter a name for the ADF Library. The preferable name is "ADF Library". Select Deploy by Default, and click Add Entry.

  5. In the Select Path Entry dialog, enter or browse to the ADF Library JAR file and click Open.

  6. The Create Library dialog reappears with the path of the JAR file filled in under the Class Path node. Click OK.

  7. The Add Library dialog reappears with the ADF Library entry filled in under the Project node. Click OK.

    Figure 44-14 Add Library Dialog

    Add library dialog.
  8. The Project Properties dialog reappears with the JAR file added to the list of libraries. Click OK.

44.3.3 What Happens When You Add an ADF Library JAR to a Project

When you add an ADF Library JAR to a project, either by using the Resources window 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 44-15 shows the empty Data Controls panel for a consuming project before the ADF Library was added.

Figure 44-15 Data Controls Panel of the Consuming Project

Data control panel of the consuming project.

Figure 44-16 shows the adflibview1 ADF Library being added to the consuming project.

Figure 44-16 Adding the ADF Library JAR to the Project

Resource Palette Add to Project.

Figure 44-17 shows several data controls from the ADF Library added to the Data Controls panel in the consuming project.

Figure 44-17 Consuming Project Data Controls Panel with Added Application Modules

Consuming project with added Data Controls.

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 44-3 lists the effects on several JDeveloper windows.

Table 44-3 JDeveloper Window After Adding an ADF Library

Added Component Data Controls Panel Creation Wizards Components window

Data controls

Data control appears.

   

Application module

Application module appears.

   

Business components

 

Entity objects available in view object creation wizard. View objects in JAR also available for use.

 

Task flows

   

Task flows appear in Components window.

Page template

 

Page template available during JSF creation wizard.

 

Declarative components

   

Tag library appears in Components window. Declarative component appears in the list.


44.3.4 What You May Need to Know About Using ADF Library Components

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.

44.3.4.1 Using Data Controls

When you add a data control to a project, the data control appears in the Data Controls panel. If you are using the Resources window, you have the option of dragging and dropping the data control from the Resources window onto the Data Controls panel, and then dragging and dropping from the Data Controls panel onto the page.

44.3.4.2 Using Application Modules

When you add an application module to a project, the application module appears in the Data Controls panel. If you are using the Resources window, you have the option of dragging and dropping the application module item from the Resources window 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.

44.3.4.3 Using Business Components

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 44-18.

Figure 44-18 Creating View Object Using Entity Objects from ADF Library

Create View Object dialog.

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.

44.3.4.4 Using Task Flows

Task flows added to a project will appear in the Components window when you are adding components to a JSF page. If you are using the Resources window, you can also drag and drop the task flow directly from the Resources window onto another task flow or page, as shown in Figure 44-19.

Figure 44-19 Using the Resources Window to Drag and Drop Task Flows

Using Task Flow.

For more information about creating task flows, see Chapter 20, "Getting Started with ADF Task Flows."

44.3.4.5 Using Page Templates

When you add a page template to a project, the template will not be exposed in the Applications window. 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 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 SummitTemplate from an ADF Library, when you use the wizard to create a JSF page, SummitTemplate will appear in the wizard, as shown in Figure 44-20. For information on how to use page templates and create a JSF page, see Section 26.2, "Using Page Templates" and the Developing Web User Interfaces with Oracle ADF Faces.

Figure 44-20 Using a Page Template from ADF Library

Using page template.

44.3.4.6 Using Declarative Components

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 Components window, and the declarative components will be available for selection. For information about creating and using declarative components, see the Developing Web User Interfaces with Oracle ADF Faces.

44.3.5 What You May Need to Know About Differentiating ADF Library Components

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.

Note:

The tooltip for items in the Data Controls panel varies depending on whether or not the node has ever been opened in this session. To ensure that you are seeing the most complete tooltip, you should expand the item.

44.3.6 What Happens at Runtime: How ADF Libraries are Added to a Project

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 44-21 shows the ADF Library and the path to the JAR as defined for a project.

Figure 44-21 Edit Library Definition Dialog Showing the ADF Library in the Class Path

Edit Library Definition dialog.

Note:

Once an ADF Library JAR is created, any Java source used to create the component is not available in the JAR. If you want your consumers to have access to the source, such as for debugging, they must be delivered separately (usually in ZIP files). The consumer can then designate those ZIP files as the related component source for the Source Path entry in their ADF Library Libraries and Classpath entry in their own projects.

44.4 Removing an ADF Library JAR from a Project

You can use the Resources window 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.

44.4.1 How to Remove an ADF Library JAR from a Project Using the Resources Window

The Resources window allows you to remove previously added ADF Library JARs from a project using a simple command.

Before you begin:

It may be helpful to have an understanding of the options that are available to you when you package an ADF component. For more information, see Section 44.4, "Removing an ADF Library JAR from a Project."

You may also find it helpful to understand functionality that can be used with packaging an ADF component. For more information, see Section 44.1.3, "Additional Functionality for Reusable ADF Components."

You will need to complete this task:

Add the ADF Library JAR using the Resources window. For more information, see Section 44.3, "Adding ADF Library Components into Projects."

To remove an ADF Library JAR from the project using the Resources Window:

  1. From the main menu, choose Window > Resources.

  2. In the Applications window, select the project that has the ADF Library JAR you want to remove.

  3. In the Resources window, locate the ADF Library JAR you want to remove from the current project.

  4. Right-click the JAR and choose Remove from Project.

44.4.2 How to Remove an ADF Library JAR from a Project Manually

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.

Before you begin:

It may be helpful to have an understanding of the options that are available to you when you package an ADF component. For more information, see Section 44.4, "Removing an ADF Library JAR from a Project."

You may also find it helpful to understand functionality that can be used with packaging an ADF component. For more information, see Section 44.1.3, "Additional Functionality for Reusable ADF Components."

You will need to complete this task:

Add the ADF Library JAR manually. For more information, see Section 44.3, "Adding ADF Library Components into Projects."

To remove an ADF Library JAR from the project manually:

  1. In the Applications window, double-click the project.

  2. In the Project Properties dialog, select the Libraries and Classpath node.

  3. In the Classpath Entries list, select ADF Library and click Edit.

  4. In the Edit Library Definition dialog, select the ADF Library JAR you want to remove under the Class Path node, and click Remove.

  5. Click OK to accept the deletion, and click OK again to exit the dialog.