33 Reusing Application Components

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

33.1.2 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, RCconnect, rcconnect2, and StoreFront. In this example, StoreFront contains the ADF Library component, adflibStorFrontService.jar.

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.

Figure 33-1 Resource Palette Showing ADF Library Structure

33.1.3 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 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 View, the Model project is a dependent project with the deployment profile option (adflibmodel1) selected, as shown in Figure 33-2.

Figure 33-2 Edit Dependencies Dialog with Deployment Profile Option

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.

Figure 33-3 Resource Palette Showing adflibView1.jar and adflibModel.jar Extension Libraries

When you select adflibView1.jar in the Resource Palette and choose Add to Project from the context menu, both adflibView1.jar and 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.

Figure 33-5 Edit Dependencies Dialog Used to Built adflibview2.jar

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 adflibView1.jar and adflibModel.jar shown in Figure 33-3.

Figure 33-6 Resource Palette Showing adflibView2.jar Extension Libraries

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.

33.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:

You should already created a project and determine whether it has dependent projects and JAR that need to be packaged.

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

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

2. In the Project Properties dialog's left pane, select Deployment and then click New.

3. In the Create Deployment Profile dialog, select ADF Library JAR file for archive type, enter a name for the deployment profile, and click OK.

   Figure 33-7 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 33-8.

   Figure 33-8 ADF Library JAR 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 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 (FOD_webapp).

      Figure 33-9 ADF Library Deployment 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 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 33.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 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.

   Figure 33-10 Connections Page of the Edit ADF Library JAR Deployment Profile Properties Dialog

   
   

7. 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 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 33-11 ADF Library JAR Deployment Profile Properties Dialog JAR Option

   
   

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

   Figure 33-12 ADF Library JAR Deployment Profile Properties Dialog ADF Validation

   
   

9. Click OK to finish setting up the deployment profile.

10. In the Application Navigator, 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.

33.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 Resource Palette 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 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.

33.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:

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:

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

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

8. In the JDeveloper of 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 OK. This should be the same location specified by the producer 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 click OK again.

33.3.1 How to Add an ADF Library JAR into a Project using the Resource Palette

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:

1. From the View menu, choose Resource Palette.

2. In the Resource Palette, click the New icon, and then choose New Connection > 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 33.1.1.5, "Selecting Paths and Folders."

4. Click OK.

   The new ADF Library JAR appears under the connection name in the Resource Palette.

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 33-13 shows a Resource Palette with a tooltip message that shows package information for a business component.

   Figure 33-13 Tooltip Message for a Connection in the Resource Palette

   
   

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 33-14.

   Figure 33-14 Confirm Add 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 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.

33.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:

You should already have an ADF Library JAR.

To add a component to a project manually:

1. In the Application Navigator, 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, 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.

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

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 33-15 Add Library Dialog

   
   

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

33.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 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-16 Data Controls Panel of the Consuming Project

Figure 33-17 shows the adflibStoreFrontService ADF Library being added to the consuming project.

Figure 33-17 Adding the ADF Library JAR to the Project

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

Figure 33-18 Consuming Project Data Controls Panel with Added Application Modules

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.

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

33.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 33-19.

Figure 33-19 Creating View Object Using Entity Objects from ADF Library

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.

33.3.4.4 Using Task Flows

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.

Figure 33-20 Using the Resource Palette to Drag and Drop Task Flows

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

33.3.4.5 Using Page Templates

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.

Figure 33-21 Using a Page Template from ADF Library

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

33.3.6 What Happens at Runtime: Adding ADF Libraries

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.

Figure 33-22 Edit Library Definition dialog showing the ADF Library in the Class Path

33.4.1 How to Remove an ADF Library JAR from a Project Using the Resource Palette

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

To remove an ADF Library JAR from the project using the Resource Palette:

1. From the View menu, choose Resource Palette.

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

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

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

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

To remove an ADF Library JAR from the project manually:

1. In the Application Navigator, 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.