|Oracle® Fusion Applications Developer's Guide
11g Release 1 (11.1.3)
Part Number E15524-03
This chapter describes how to set up your JDeveloper workspace and projects, add libraries to projects, integrate Oracle Fusion Middleware extensions, create a database connection, implement Oracle Enterprise Crawl and Search (ECSF), and deploy Oracle SOA Suite.
Whenever you create new projects, you must first create an application using the Fusion Web Application (Oracle ADF) template. The system will then automatically create the data model and user interface projects for you. The default names that JDeveloper provides for these projects are
After your projects have been created, you must manually add the Applications Core library to the data model project and the Applications Core Tag library to the user interface project.
This chapter discusses:
Technology scopes are attributes on the project that can be used to identify the different technologies used for that particular project. These attributes are used only within JDeveloper to assist you as you work. With technology scopes, the choices presented to you in the New Gallery and in the menus and palettes are filtered so that you see only those items that are most relevant to you as you work. Technology scopes have no effect on the data in the project itself.
The JDeveloper online Help has more information.
The application's Enterprise Archive (EAR) will be available for developers to pick up when creating a custom workspace. An administrator that provisions the environment will be responsible for providing developers with the following:
EAR locations for the various applications.
jazn-data for the various applications.
LDAP/credential store that the developer can set up for authentication.
In addition, the Oracle Fusion Applications Customization Application Wizard will create a complete development environment for customizing existing Oracle Fusion applications. See the online Help in the wizard, and "Using JDeveloper for Customizations" in the Oracle Fusion Applications Extensibility Guide.
Use these directions to add the Applications Core and Applications Core (Attachments Model) libraries to the data model project. The default name, provided by JDeveloper, for this project is
To add the Applications Core and Applications Core (Attachments Model) libraries to a data model project:
Choose Application Navigator > Model project. Right-click and choose Project Properties from the menu.
Choose the Libraries and Classpath category. Click Add Library to open the Add Library dialog.
Select the Applications Core and Applications Core (Attachments Model) libraries from the list of available libraries. Click OK to save your selection and close the Add Library dialog.
The libraries are now displayed in the Classpath Entries region of the Libraries and Classpath dialog, as shown in Figure 3-1.
Click OK to save your changes.
Use these directions to add the Applications Core Tag Library to the user interface project. The default name provided by JDeveloper for this project is
To add the Applications Core Tag library to the user interface project:
Choose Application Navigator > ViewController project. Right-click and choose Project Properties from the menu.
Choose the JSP Tag Libraries category. Go to the Distributed libraries folder and click Add to open the Add Library dialog.
Select the Applications Core (ViewController) 184.108.40.206.0 tag library from the list of available libraries. Click OK to save your selection and close the Add Library dialog.
The Applications Core (ViewController) 220.127.116.11.0 is now displayed under the Distributed libraries folder on the JSP Tag Libraries dialog, as shown in Figure 3-2.
Click OK to save your changes.
Choose Application Navigator > ViewController project. Right-click and choose Project Properties from the menu.
Choose the Dependencies category and select the Model.jpr.
Even if you are only using the user interface project you must still initialize the data model project as they are dependent on each other.
Click OK to save your changes and close the Project Properties dialog.
The most common use of Applications Core setup UIs is through Oracle Fusion Functional Setup Manager tasks that invoke the UIs running on the Applications Core Setup Java EE application. Applications Core setup UIs are part of the Applications Core (Setup UI) shared library, which is hosted centrally in the Applications Core Setup Java EE application. As a result, developers typically will not need to include the shared library in their own Java EE applications.
Every Oracle Fusion application registers ADF task flows with the Functional Setup Manager, which provides a single, unified user interface that allows implementers and administrators to configure all applications by creating set up data.
For example, a Human Resources application can register setup activities such as "Create Employees" and "Manage Employee Tree Structure." See the Oracle Fusion Applications Information Technology Management, Implement Applications Guide.
To make these task flows available to developers, implementers or administrators, a developer integrates the desired Applications Core setup UI task flows with Functional Setup Manager. For information about specific task flows, see:
The most common use of setup UIs is through Oracle Fusion Functional Setup Manager tasks. This is true even for product-specific tasks that invoke the task flows with parameters that restrict the results to a single object or set of objects.
To determine your requirements, familiarize yourself with these three scenarios and decide which one best fits your needs. The first two patterns are the typical use cases. The third is for approved exceptions only.
Scenario 1 is a generic setup task that invokes a setup taskflow running in the Applications Core Setup Java EE application. For example, you want to give your product administrator roles access to the generic Manage Descriptive Flexfields setup task.
Scenario 2 is a product team-specific setup task that invokes a setup taskflow running in the Applications Core Setup Java EE application and passes in product-specific parameters to restrict the objects to only those relevant to this specific task. For example, you want to give your product administrator roles access to a Manage GL Descriptive Flexfields setup task that launches the Manage Descriptive Flexfields setup UI for descriptive flexfields belonging to the GL module only.
Scenario 3 is a product team-specific setup task that invokes a setup taskflow running in the product team's own Java EE application. This scenario is for approved exceptions only. For example, you plan to embed the setup UI within another UI in your own product team's Java EE application. For instance, the Manage Item Categories UI in Product Information Management (PIM) embeds the Manage Extensible Flexfields setup UI.
Follow the instructions in Table 3-1 that are relevant to your scenario to integrate Applications Core setup UIs into Functional Setup Manager.
Table 3-1 Instructions for Each Scenario
|Step||Scenario 1||Scenario 2||Scenario 3|
Follow Functional Setup Manager guidelines to create product-specific setup tasks in the Application Design Repository. Tailor the behavior of the setup UI by passing allowed values to the task flow parameters. Decide what Applications Core setup UI task flows that you want to incorporate and locate the chapter (see Section 3.5.1, "What You May Need to Know About Setup UIs in Oracle Fusion Functional Setup Manager") that describes each task flow and its parameter values.
Product teams should set the value of the Enterprise Application field (in the Application Design Repository) to the appropriate Java EE application for any of their product-specific Functional Setup Manager tasks that use Applications Core setup task flows. Typically, this should be set to the Applications Core Setup Java EE application.
Ensure product team roles inherit the appropriate Applications Core duty role. The duty roles support securing the setup tasks so only authorized users have access.
If you intend to integrate a product-team specific setup UI and it will run in your product team's own Java EE application, your application will need to include the Applications Core shared library.
For any of the duty roles and their associated privileges that your application inherits, include permissions for those privileges in your application's
A connection to a valid database is necessary to run most, if not all, applications.
To create a database connection:
In JDeveloper, choose Application Resources > Connections. Right-click and choose New Connection > Database from the menu.
Add the following connection details for the ApplicationDB connection name as shown in Figure 3-3.
Connection Name: The value for the connection name must be ApplicationDB.
Connection Type: Choose Oracle (JDBC).
Username and Password: Enter the database username and password.
Deploy Password: Select this checkbox.
Host Name: This is the default host name if the database is on the same machine as JDeveloper. If the database is on another machine, type the name (or IP address) of the computer where the database is located.
JDBC Port: This is the default value for the port used to access the database. If you do not know this value, check with your database administrator.
SID: This is the default value for the SID that is used to connect to the database. If you do not know this value, check with your database administrator.
Click Test Connection. (Database listener Port). If the database is available and the connection details are correct, the message Success! is displayed. If not, review and correct the information that you entered.
Click OK. The connection now appears below the Application Resources Connections folder as shown in Figure 3-4.
ECSF provides developers a set of tools and a framework to quickly and efficiently integrate Oracle Secure Enterprise Search (SES) into enterprise applications to expose business objects for full text search.
For more information about ECSF, see Part V, "Using Oracle Enterprise Crawl and Search Framework"
Developers use ECSF to integrate search functionality in Oracle Fusion applications by defining searchable objects and searchable attributes. Defining searchable objects and searchable attributes enables the corresponding view objects and view object attributes for search, and creates the necessary metadata for ECSF. However, before you can define searchable objects and searchable attributes, you must add the Search navigation tab to the overview editor in JDeveloper.
For more information about defining searchable objects, see Chapter 28, "Creating Searchable Objects."
To add the Search navigation tab to the overview editor in JDeveloper, download the JDeveloper extension for ECSF.
To download the JDeveloper extension for ECSF:
If you have trouble initializing Java Virtual Machine (JVM), launch JDeveloper by entering
jdeveloper.exe -J-Xmx125m at a command prompt.
In JDeveloper, choose Check for Updates from the Help menu.
In the Check for Updates dialog, click Next.
In the Source tab, select the Search Update Centers radio button, then select the Internal Automatic Updates checkbox.
Click Next, then select the ECSF Design Time Extension checkbox.
Click Next, then click Finish.
When prompted to restart JDeveloper, click Yes.
Once the Search navigation tab is added, the
oracle.ecsf.dt.jar file appears in the
oracle_home/jdev/extensions directory and the following files appear in the
The Search navigation tab appears in the overview editor of JDeveloper, as shown in Figure 28-3.
Use the Search navigation tab to configure the search-related properties.
For more information, see Chapter 28, "Creating Searchable Objects."
In an Oracle Fusion application, strings are not hard-coded; they are placed in resource bundles. An application can have multiple resource bundles.
However, you may need to change a specific string in all places where that string appears without having to change it on a per-instance (page/ADF BC object) basis. For instance, you may need to change "worker" to "employee," "activity" to "task," or "expenditure" to "cost." The method to use is the override resource bundle.
"Internationalizing and Localizing Pages" for information about setting up resource bundles.
"What You May Need to Know About Overriding Default Messages Globally" for general instructions on overriding a resource bundle.
This bundle is specified in the
adf-config.xml file and is created at runtime. For Oracle Fusion applications, there are two important points:
This file must be named
Although an application can have multiple resource bundles, it can have only one override resource bundle.
For information about deploying SOA, see:
"Deploying an SOA Composite Application" in the "Developing SOA Composite Applications with Oracle SOA Suite" chapter of the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
Oracle Enterprise Scheduler Service applications, also known as Oracle Enterprise Scheduler Service hosting applications, are deployed to an Oracle Enterprise Scheduler Service-configured runtime or cluster that has been pre-deployed with the base ESSAPP infrastructure Java EE application. Following standards, Oracle Enterprise Scheduler Service workspaces exist one per product family and are responsible for containing these supporting projects:
Oracle Enterprise Scheduler Service projects for containing Job, Job Set, Incompatibility and Schedule Metadata as well as source files for any Java Job implementation.
ADF data model projects for containing Parameter view object business components.
ADF user interface projects for containing Parameter task flows.
Optional servlet or UI task flow projects for development-time testing.
SuperEss consolidating the Enterprise JavaBeans deployment descriptors for the entire Oracle Enterprise Scheduler Service hosting application. See Section 3.11.2, "How to Create the SuperEss Project in the ADF UI Workspace."
All the projects in an Oracle Enterprise Scheduler Service application, regardless of their content type, should have an ADF Business Components Shared Library deployment profile.
A typical Oracle Enterprise Scheduler Service workspace structure resembles Figure 3-5.
In Oracle Fusion Applications, all Oracle Enterprise Scheduler Service workspaces must contain a SuperEss project that contains the EJB deployment descriptors to register the hosted application with the ESSAPP base application, and to register both the MetadataService and RuntimeService EJBs. This technique avoids having multiple projects with conflicting deployment descriptors in a single deployment archive (EAR).
RuntimeService and MetadataService beans are hosted by the ADF UI application and the Oracle Enterprise Scheduler Service hosting application.
If you are creating a new Oracle Enterprise Scheduler Service workspace or your Oracle Enterprise Scheduler Service workspace does not already have a SuperEss project, create one using these steps:
In JDeveloper, create the SuperEss project by creating a new Generic Project named SuperEss.
In the project properties, create a new EJB-JAR deployment profile.
In the File Groups Properties, click New to create a new file group.
Name it and set the directory path of both to
In the source directory, create the
src/META-INF directory.Create the
weblogic-ejb.jar.xml files. See "Assembling the Scheduler Sample Application" in the Oracle Fusion Middleware Developer's Guide for Oracle Enterprise Scheduling Service. Save the files in the
After completing these steps, the SuperEss project will be complete. Follow Section 3.10.2, "How to Build the EAR/MAR Profiles" to build the EAR/MAR deployment profiles.
Oracle Enterprise Scheduler Service-hosted applications are built into EAR files and deployed as Java EE applications. The EAR archive must contain the SuperEss EJB JAR, the MAR archive containing all Oracle Enterprise Scheduler Service metadata, and all the Job and Job-related classfiles using JARs in the
APP-INF/lib directory. Follow these steps to create the appropriate deployment profiles.
Oracle Enterprise Scheduler Service is used in the instructions because it is the primary, but not only, use case.
To simplify patching of Oracle Enterprise Scheduler Service metadata artifacts and align with code-level patching, it is essential to have project-level deployment artifacts. To support this requirement, EARs with multiple MAR files can be deployed. This section describes what must be done to properly build Oracle Enterprise Scheduler Service workspaces to support project-level MARs.
In contrast to standard MAR deployment, in which a single .mar file is created as a metadata aggregate from contributors defined from one or more projects in the workspace, this approach focuses on the creation of a JAR-based deployment profile in each project where the target file is named with a .mar extension. The resultant .mar files are then deployed into the workspace's
jlib folder, which is added to the top-level directory of the EAR by the EAR deployment profile.
Follow these steps to implement the project-level MAR deployment.
Prepare the Workspace EAR deployment profile.
Open your Oracle Enterprise Scheduler Service Workspace in JDeveloper.
Open the Application Properties, select the Deployment panel, choose your application's EAR deployment profile and click Edit.
These steps will need to be repeated if you have multiple EAR deployments for development or test purposes.
Select File Groups and click New to create a new file group. Leave the type as Packaging and name this group MAR Group.
Leave the remaining values at their defaults and click OK.
Select the Contributors heading beneath the new MAR Group file group and click Add.
Browse to find the workspace-level
jlib directory and click OK.
In the Filters heading beneath the MAR Group, remove all the filters and add these two rules so they display in this order:
Prepare each metadata project JAR(MAR) deployment profile.
These steps will need to be repeated if you have multiple projects containing Oracle Enterprise Scheduler Service metadata.
Select the Oracle Enterprise Scheduler Service metadata containing project and open the project properties.
Select the Deployment panel and click New.
If necessary, select the JAR File archive type and provide a meaningful profile name, such as <ProjectName>_MAR.
In the JAR Options panel, change the JAR File destination to point to the workspace-level
jlib directory, and change the file's .jar extension to .mar.
Select File Groups > Project Output > Contributors and de-select Project Output Directory and Project Dependencies.
Click Add to add a new contributor and browse to and select the
essmeta project-level directory.
Select File Groups > Project Output > Filters and confirm the addition of the relevant Oracle Enterprise Scheduler Service metadata files.
Deploy as JAR and verify.
Complete the Workspace EAR deployment profile.
These steps will need to be repeated if you have multiple EAR deployments for test or development purposes.
Open the Application Properties.
Select the Deployment panel and choose the EAR deployment profile for your application.
In the MAR Group file group, select Filters and ensure that all of your project level MAR archives are selected.
Select the Application Assembly heading and de-select the workspace-level MAR profile.
Select the Profile Dependencies in the left-hand side.
Check the boxes for each of the new JAR-based MAR profiles.
Deploy as EAR and verify.
The EAR profile pulls together all of the previously-created EJB and MAR profiles to build the Oracle Enterprise Scheduler Service-hosted application. All the Oracle Enterprise Scheduler Service workspace projects should have ADF library JAR deployment profiles, and those with Job-supporting implementation classes should be deployed to a directory that can be added to the Oracle Enterprise Scheduler Service EAR's contributor list.
To create the EAR profile, follow these steps:
Open the Application Properties and select the Deployment panel.
Click New to create a new deployment, choose EAR File as the profile type, and provide a unique name.
In the Application Assembly, choose the SuperESS EJB-JAR profile and nothing else.
Select the File Groups menu entry and click New, giving the name APP-INF/lib and assigning the target directory to
ess workspace root path
Under the APP-INF/lib File Group's contributors, add the directory that holds all of the Job-supporting Implementation classes (not data model projects with ADF Business Components for parameter view objects or parameter task flows).
Select the File Groups menu entry and click New, giving the name MAR Group and leave the target directory empty. Under the MAR Group's contributors, add the directory that holds all the project level mar files (such as
Note that the EAR profile should contain only the SuperEss EJB JAR, the MAR, and the JAR files for the Job implementation classes. The Oracle Enterprise Scheduler Service hosting application's EAR file must not contain JARs, descriptors or other artifacts for UI, data model or services functionality. Should your application contain projects with servlet or UI task flows for development testing, they must be bundled into a separate, UI-specific, set of EAR/MAR deployment profiles.
When deploying an Oracle Enterprise Scheduler Service hosting application, the target managed server must have the ESSAPP base application pre-deployed and configured to run against a working Oracle Enterprise Scheduler Service database schema.
For deployment from JDeveloper, you will need to create an Application Server connection in the JDeveloper resources palette before or as part of the deployment activity using the New Connection feature. Once your Oracle Enterprise Scheduler Service application is ready for deployment, including all requisite project and application-level profiles, you can initiate deployment by following these steps:
Click Deploy > <ear profile name> from the Application menu.
Choose Deploy to Application Server and click Next.
If no application servers are defined, or the one to which you wish to deploy is not defined, click Add an Application Server. Otherwise, select the server. Do not click Next yet.
De-select the Deploy to all server instances in the domain option, because certain libraries needed for deployment of the Oracle Enterprise Scheduler Service hosting application will not be targeted to all the managed servers, and deployment will fail.
Choose the appropriate managed server and click Next.
Click Finish to begin deployment.
JDeveloper will build the EJB JAR and the MAR, and bundle those archives, along with the JAR files, in the
APP-INF/lib contributor location. This packaged archive will be sent to the managed server for deployment. During deployment, the Oracle Enterprise Scheduler Service hosting application will register itself through the ESSAPP base application using the ESSAppEndpoint descriptor in your
Once deployment is finished, jobs can be submitted programmatically or through the Oracle Enterprise Scheduler Service UI submission task flows. These methods are documented in the Oracle Fusion Middleware Developer's Guide for Oracle Enterprise Scheduling Service.
Before you can deploy your web project, you need to complete a number of preliminary steps. These include setting up your web project and configuring your user interface project; creating the SuperESS project; creating the appropriate deployment profiles; and creating and setting up Oracle WebLogic Server.
When you choose the Oracle Fusion Applications Developer role when starting JDeveloper, many settings default automatically for you. However, there are still certain options that you need to set manually to configure your project.
This section discusses the specific options that need to be set manually to configure your user interface project. The default name for the project that JDeveloper provides is
This section describes how to configure your user interface project in JDeveloper.
To configure your user interface project:
Choose Application Navigator > ViewController project. Right-click and choose Project Properties from the menu.
Choose the Project Source Paths category to display the Project Source Paths dialog.
In the Default Package field, enter the name of your default package, as shown in Figure 3-6.
Many objects are generated automatically and are stored in the default package.
Choose the ADFm Sources category from the Project Source Paths hierarchy to display the Project Source Path: ADFm Sources dialog, as shown in Figure 3-7.
The location for all the ADF Metadata sources is the location that is entered in the ADFm Source Directory field. You should not have to change the default location.
Choose the Web Application category from the Project Source Paths hierarchy to display the Project Source Path: Web Application dialog, as shown in Figure 3-8.
The location for all the HTML content is the location that is entered in the HTML Root Directory field. You should not have to change the default location.
Choose the ADF Model category to display the ADF Model dialog, as shown in Figure 3-9.
The location of the page definition files is based on a combination of the PageDef sub-package value, the default package location, and the ADFm Sources directory.
Choose the Deployment category to display the Deployment dialog.
Select New to open the Create Deployment Profile dialog, as shown in Figure 3-10.
Choose ADF Library Jar File from the Archive Type list.
Enter the Name as Adf<projName> in accordance with the Package Structure and Naming Standards.
Click OK to save the new deployment profile and close the Create Deployment Profile dialog.
The new deployment profile is now listed on the Deployment dialog.
Choose the JSP Tag Libraries category to display the JSP Tag Libraries dialog, as shown in Figure 3-11.
Verify that you have the following tag libraries listed under the Distributed libraries folder:
Applications Core (ViewController) 18.104.22.168.0
Trinidad HTML Components 1.2
You may have to include additional tag libraries for other features, such as Data Visualization Tools (DVT) and WebCenter. For more information about adding tag libraries to your user interface project, see Section 3.4, "Adding the Applications Core Tag Library to Your User Interface Project.".
Choose the Libraries and Classpath category to display the Libraries and Classpath dialog, as shown in Figure 3-12.
Verify that the libraries listed in Figure 3-12 have been attached to your user interface project. As with tag libraries, you may have to add additional libraries.
Choose the Resource Bundle category to display the Resource Bundle dialog, as shown in Figure 3-13.
Verify that the Resource Bundle Type is set to Xliff.
The default settings will be correct when you start JDeveloper using the Oracle Fusion Applications Developer role.
Choose the Technology Scope category to display the Technology Scope dialog, as shown in Figure 3-14.
Verify that the technology scopes that are selected in Figure 3-14 are selected for your project.
This selection is limited to what is available, by default, in the New Gallery. To see other types of objects, choose All technologies from the New Gallery.
Follow the steps in Section 3.10.1, "How to Create the SuperEss Project". The differences are that the
ejb-jar.xml file will have no ESSAppEndpoint MDB and the
weblogic-ejb.jar.xml file will be empty.
Deployment is the process of packaging application files and artifacts and transferring them to a target application server to be run. During application development using JDeveloper, developers can test the application using Integrated WebLogic Server that is built into the JDeveloper installation, or they can use JDeveloper to directly deploy to a standalone application server.
After the application has been developed, administrators can deploy it to production application servers.
This section assumes that you are deploying a web project to Standalone WebLogic Server. Creating deployment profiles is not necessary if you are running the project in Integrated WebLogic Server from within JDeveloper. In this case, JDeveloper, behind the scenes, creates an in-memory deployment profile.
For other deployment options, see "Deployment Techniques for Development or Production Environments" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
To deploy the web project to Standalone Weblogic Server, you must:
Create a Web Application Archive (WAR) deployment profile. To create the WAR deployment profile, see "How to Create Deployment Profiles" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Once you have defined the WAR, create an EAR deployment profile that includes the WAR profile, for the application. To create an EAR deployment profile, see "Creating an Application-Level EAR Deployment Profile" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Create, if necessary, and prepare the standalone application server for deployment. To run ADF applications, you must install the standalone application server with the ADF runtime. You can include the ADF runtime during a new application server installation or you can install the ADF runtime into an existing application server installation. See "How to Install the ADF Runtime to the Application Server Installation" and "How to Create and Extend Oracle WebLogic Server Domains" in the Oracle Fusion Middleware Administrator's Guide for Oracle Application Development Framework.
Deploy the application using one of these methods:
Oracle Enterprise Manager Fusion Middleware Control
WebLogic Scripting Tool (WLST) commands (see "Deployment Commands" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference) or WebSphere Application Server (wsadmin) commands
Command scripts and Ant scripts
Oracle WebLogic Administration Console or IBM WebSphere Administrative Console