OracleAS Portal 10g Developer Kit (PDK)
Installing the PL/SQL Generator

Contents

Introduction
Contents
Requirements
Deploying the PL/SQL Generator
    Deploying the PL/SQL Generator to a stand-alone OC4J server
        Manual Deployment
        Hot Deployment
    Deploying the PL/SQL Generator to an OracleAS 10g OC4J Instance
        Using the Application Server Control
        Using the dcmctl utility
Generating the provider and portlet packages
Publishing the generated PL/SQL portlet
     Installing the provider and portlet packages into the database
     Registering the database provider with OracleAS Portal 10g
     Adding the generated PL/SQL portlet to a portal page
PL/SQL Generator supported tags

Introduction

The PL/SQL Generator is a Web application that creates installable PL/SQL code for a database provider and its portlets based on the provider and portlet definitions that are stored in the form of an XML file. This document describes how to install and configure the PL/SQL Generator. It also explains how to install the generated PL/SQL code into the Oracle database, register the database provider, and publish the PL/SQL portlet to your portal page.

Contents

This section describes the content of the PL/SQL Generator download. It includes one application file, one documentation file and supporting image files, and a sample provider and portlet definition XML file.

Application File

• plsqlgenerator.ear - Contains files necessary to run the PL/SQL Generator.

• Installing.the.PLSQLGenerator.html - This document.
• Fig*.gif - Screenshot images used in this document.

• provider.xml  - The sample provider and portlet definition XML file is an input for the PL/SQL Generator. The XML file starts with the <provider> tag, ends with the </provider> tag, and includes one or many portlet definitions. Each portlet definition begins with the <portlet> XML tag and ends with the </portlet> tag. A portlet definition includes the XML tags that specify values for the portlet record attributes and the XML tags that enable the links in the portlet header. For example, the <name> tag specifies the portlet name in the provider domain and the <title> tag specifies the portlet display name or the portlet title. The input XML file MUST have the <name> and <title> tags for each portlet in the provider.xml file. It can have additional tags other than the ones mentioned in the provider.xml file. The list of tags supported by the PLSQL Generator are provided in the PL/SQL Generator Supported Tags section.

Requirements

• Oracle Database 9i and above.
• OracleAS Portal 10g and above.
• PDK Framework for Java (JPDK) v9.0.4 or above.

Deploying the PL/SQL Generator

A. Deploying the PL/SQL Generator to a stand-alone OC4J server.

Manual Deployment

Copy the plsqlgenerator.ear file into the applications subdirectory under the OC4J home directory. Usually, this directory is:

$OC4J_HOME/j2ee/home/applications

Note: $OC4J_HOME is the root directory of your stand alone OC4J installation. You can also find directories named bin, jdk, lib, jlib etc. under this directory.

Add the following line to the $OC4J_HOME/config/server.xml file:

<application name="plsqlgenerator" path="../applications/plsqlgenerator.ear" />

Bind the application to the default site by adding the following line to the $OC4J_HOME/config/http_web_site.xml file:


<web-app application="plsqlgenerator" name="plsqlgenerator" root="/plsqlgenerator" />

Start up the OC4J server. This will automatically deploy the application based on the information specified in Step 3. To start up the OC4J instance, run the following command from the $OC4J_HOME/j2ee/home directory:


java -jar oc4j.jar

Access PL/SQL Generator using the following URL:

http://<hostname>:<OC4J_port>/plsqlgenerator/generator.html

Hot Deployment

This method explains the concept of hot deployment where you can deploy a Web application without restarting the OC4J server.

Copy the plsqlgenerator.ear file into the OC4J home directory. Usually, this directory is:

$OC4J_HOME/j2ee/home

Verify whether your OC4J server is running. If not, start the OC4J server by running the following command from the $OC4J_HOME/j2ee/home directory:


java -jar oc4j.jar

Deploy the plsqlgenerator.ear file to the OC4J server by running the following command from the $OC4J_HOME/j2ee/home directory:

java -jar admin.jar ormi://<host>:<ormi_OC4J_port> <adminuser> <password>
-deploy -file plsqlgenerator.ear -deploymentName plsqlgenerator

Note: ormi_OC4J_port is the port number for the ORMI protocol.

You should see output similar to the following upon the successfull deployment:

Notification ==> Application Deployer for plsqlgenerator STARTS [ 2004-03-26T10:05:41.627PST ]
Notification ==> Undeploy previous deployment
Notification ==> Copy the archive to /private/oracle/OC4J_904/j2ee/home/applications/plsqlgenerator.ear
Notification ==> Unpack plsqlgenerator.ear begins...
Notification ==> Unpack plsqlgenerator.ear ends...
Notification ==> Initialize plsqlgenerator.ear begins...
Notification ==> Initialize plsqlgenerator.ear ends...
Notification ==> Initialize plsqlgenerator begins...
Notification ==> Initialize plsqlgenerator ends...
Notification ==> Application Deployer for plsqlgenerator COMPLETES [ 2004-03-26T10:05:42.454PST ]

Bind the PL/SQL Generator to the OC4J server by running the following command:

java -jar admin.jar ormi://<host>:<ormi_OC4J_port> <adminuser> <password> -bindWebApp plsqlgenerator plsqlgenerator http-web-site /plsqlgenerator

Access the PL/SQL Generator using the following URL:

http://<hostname>:<OC4J_port>/plsqlgenerator/generator.html

B. Deploying the PL/SQL Generator to an OracleAS 10g OC4J Instance.

Using the Application Server Control

1. Logon to the Application Server Control of the OracleAS 10g instance as ias_admin using the following URL:

   http://<hostname>:<iAS_instance_admin_port>

2. In the System Components section on the OracleAS 10g instance home page, select an OC4J instance to which you would like to deploy the PL/SQL Generator. For example, home.
   Note: You can also create a new OC4J instance.

   
   Figure 1. The OracleAS 10g instance home page.

3. In the OC4J instance home page, select the Applications tab.

   
   Figure 2. The OC4J instance home page.

4. In the Applications tab of the OC4J instance home page, click the Deploy EAR file button. This starts the Deploy Application wizard.

   
   Figure 3. The Applications tab of the OC4J instance home page.

5. In the initial page of the Deploy Application wizard, define the location of the plsqlgenerator.ear file in the J2EE Application field and specify the application name for the PL/SQL Generator in the Application Name field. For example, plsqlgenerator. Optionally select the parent application in the Parent Application field or leave it set to the default value. Click the Continue button.

   
   Figure 4. The inital page of the Deploy Application wizard.

6. In the URL Mappings for Web Module page of the Deploy Application wizard, enter the URL to which you want to map the PL/SQL Generator in the URL Mapping field. The default value is /plsqlgenerator. Click the Finish button.

   
   Figure 5. The URL Mappings for Web Module page of the Deploy Application wizard.

7. In the Review page of the Deploy Application wizard, review your selections and statistics for the PL/SQL Generator you are deploying. To change any of the wizard settings, use the Back button to navigate to the wizard page to which you want to make changes. When you are ready to deploy the application, click the Deploy button.

   
   Figure 6. The Review page of the Deploy Application wizard.

8. The Processing: Deploy page is displayed to inform you that the PL/SQL Generator is being deployed to the OC4J instance. Wait until the the process ends and the Confirmation page is displayed.

   
   Figure 7. The Processing: Deploy page.

9. Click OK in the Confirmation page after successful deployment of the PL/SQL Generator.

   
   Figure 8. The Applications tab of the OC4J instance home page.

10. Verify that the plsqlgenerator application is listed in the Applications tab on the OC4J instance home page.
    
    

    Figure 9. The OracleAS 10g instance home page.

11. Access the PL/SQL Generator using the following URL:

http://<hostname>:<iAS_instance_listen_port>/plsqlgenerator/generator.html

Using the dcmctl utility

1. Copy the plsqlgenerator.ear file into the root directory of the OracleAS 10g instance. You will find directories named bin, Apache, lib, jlib etc. under this directory.
2. Deploy the PL/SQL Generator by runnig the following command:

   $IAS_HOME/dcm/bin/dcmctl deployapplication -file $IAS_HOME/plsqlgenerator.ear
   -a plsqlgenerator -co <OC4J_instance_name>

   Note: $IAS_HOME is the root directory of your OracleAS 10g installation.

   You should see output similar to the following upon the successfull deployment:

   1 BC4J
   2 BC4JManager
   3 IsWebCacheWorking
   4 plsqlgenerator

3. Access the PL/SQL Generator using the following URL:

http://<hostname>:<iAS_instance_listen_port>/plsqlgenerator/generator.html

Generating the Provider and Portlet Packages

The PL/SQL Generator creates installable PL/SQL code contains provider and portlet packages in the form of a SQL file. To generate the SQL file, perform the following steps in the PL/SQL Generator home page:

Figure 10. The PL/SQL Generator home page.

1. Click the Browse button and select the source XML file into the Source XML File field. The data in the <name> tag which is present under the <portlet> tag MUST NOT contain any spaces in it. The generator uses the information provided in the <name> tag for the portlet package name. The source XML file should look similar to the one that is shown in the PLSQL Generator Supported Tags section of this document.
    
2. In the Provider Name field, enter the name of the provider. The provider name MUST NOT contain any spaces in it. The generator uses the value entered in the Provider Name field for the provider package name. For example, MYFIRSTGENERATEDPROVIDER.
    
3. Click the Generate button to generate the SQL file that contains the installable PL/SQL code for the provider and portlet packages. Upon successful generation, the browser prompts you to select between saving or opening the generated SQL file.
    
4. Save the generated SQL file as a file of the SQL type.
   Note: you need to change the default name from the script.jsp to your liking. For example, script.sql.

Publishing the Generated PL/SQL Portlet

A. Installing the provider and portlet packages into the database

To install the generated provider and portlet packages into the database in which you have installed OracleAS Portal 10g, perform the following steps:

1. Start a SQL*Plus session and login to the PORTAL schema.
    
2. Create a new database schema, the provider schema, that will store the generated provider and portlet packages by entering the following commands in the SQL*Plus prompt:

   create user <provider_schema> identified by <provider_schema_password>;
   
   grant resource, connect to <provider_schema>;

3. Grant EXECUTE privilege to call the OracleAS Portal 10g PL/SQL APIs to the provider schema by running the provsyns.sql script that is located in the $IAS_HOME/portal/admin/plsql/wwc directory as follows:

   @provsyns.sql <provider_schema>

   Note: $IAS_HOME is the root directory of your OracleAS 10g installation.

4. Login to the provider schema and run the generated SQL file. It should create the provider and portlet packages in the database.

B. Registering the database provider with OracleAS Portal 10g

After creating the provider and portlet packages in the database, you must register the provider with OracleAS Portal 10g before adding the PL/SQL portlet to a portal page.

1. Login to OracleAS Portal 10g as a portal administrator.
    
2. Open the Administer tab in the Portal Builder page.
    
3. Click the Portlets subtab in the Administer tab.
    
4. Click the Register a Provider link in the Remote Providers portlet.
    
5. Enter the following provider information in the first page of the Provider Registration wizard:
   • Name: A unique name of up to 200 characters for the portlet provider. This name is used by OracleAS Portal 10g internally. For example, PlsqlGeneratorProvider.
   • Display Name: This name appears in the Add Portlets page with the provider's portlets listed beneath it. For example, PLSQL Generator Provider.
   • Timeout: The number of seconds OracleAS Portal 10g should attempt to connect to the provider before displaying the timeout message. For example, 20.
   • Timeout Message: The text of the message that you want to display when OracleAS Portal 10g cannot establish contact with this portlet provider within the number of seconds specified in the Timeout field. For example, Portlet has timed out.
   • Implementation Style: The type of implementation style chosen for this portlet provider. In our case, select Database.
      
6. Click Next to proceed to the next step of the Provider Registration wizard.
    
7. The display of the second step of the wizard depends on the provider's implementation style that is selected in the first step. Enter values for the following properties required for a database provider:
   • Owning schema : <provider_schema>
   • Package Name : MYFIRSTGENERATEDPROVIDER (in our example).
     Note: Package Name should have the same value as the one that you have entered for the Provider Name field while generating the SQL script.
     
8. Click Finish to complete the provider registration.

C. Adding the generated PL/SQL portlet to a portal page

You are now ready to add the generated PL/SQL portlet to an OracleAS Portal 10g page. To add the generated PL/SQL portlet to a portal page:

1. Open a portal page where you want to add the portlet and click Edit. The page is displayed in the Graphical edit mode.
   Note: You can also add the portlet by clicking the Customize link, which enables you to make the changes that are visible only to you.
    
2. Select a portlet region in the page and click the Add Portlet icon in the region banner.
    
3. In the Add Portlets window, open the Portlet Staging Area folder and select the registered database provider (PLSQL Generator Provider). The provider should list its portlets.
    
4. Select the portlet that you want to display on your page by clicking the portlet name. This adds the portlet to the Selected Portlets list.
    
5. Click OK to return to the page editor. The portlet is displayed in the page.
    

PL/SQL Generator Supported Tags

1. <provider>
   This is the root tag of the Source XML file. The database provider can contain one or more PL/SQL portlets.
   
2. <portlet>
   The <portlet> tag contains information about each PL/SQL portlet.

Portlet XML tag	Description
<id>	Defines the portlet's unique id. This value must be unique within the provider.
<name>	Defines the portlet's name. The name should not have any spaces.
<title>	Defines the portlet's title.
<shortTitle>	Defines the portlet's short title. Used for mobile portlets.
<description>	Defines the portlet's description.
<timeout>	Specifies the portlet's timeout value in seconds.
<timeoutMsg>	Defines the text of the message that is displayed when the portlet times out.
<showEdit>	Indicates whether the portlet supports the EDIT show mode that enables the user to customize the portlet's properties. The tag can take a value of either true or false.
<showEditDefault>	Indicates whether the portlet supports the EDIT DEFAULTS show mode that enables page administrators to customize the default values of the portlet's properties. The tag can take a value of either true or false.
<showDetails>	Indicates whether the portlet can be viewed in the FULL SCREEN (Detailed) show mode. In this mode the entire browser window is dediatied to the portlet, so that the portlet can show more details that it can show when sharing the page with other portlets. The tag can take a value of either true or false.
<showPreview>	Indicates whether the portlet can be viewed in the PREVIEW show mode. The tag can take a value of either true or false.
<hasHelp>	Indicates whether the portlet supports the HELP show mode. The tag can take a value of either true or false.
<hasAbout>	Indicates whether the portlet supports the ABOUT show mode. The tag can take a value of either true or false.
<language>	Defines the portlet's default language.
<contentType>	Indicates the default content type supported by the portlet. The tag can take one of the following values: wwpro_api_provider.CONTENT_TYPE_HTML, wwpro_api_provider.CONTENT_TYPE_XML, wwpro_api_provider.CONTENT_TYPE_MOBILE.
<apiVersion>	Specifies the version of the OracleAS Portal PL/SQL API to which the portlet conforms. For OracleAS Portal 9.0.4 and earlier releases, the tag value shoud be wwpro_api_provider.API_VERSION_1.
<callIsRunnable>	Indicates whether OracleAS Portal must check for the user's credentials before displaying the portlet. It can take a value of either true or false. The default value is true.
<callGetPortlet>	Indicates whether the portal can use the portlet record data stored in the Portlet Metadata Repository (PMR) instead of contacting the provider for the portlet record. If the portlet record (specified by provider id, portlet id, and language) returned by a provider does not change, then the provider should set the value for call_get_portlet to false. This tells the portal to use the PMR instead of making calls to the provider's get_portlet and get_portlet_list functions. An example of when a provider would not want the portal to use portlet metadata from the PMR, is when the value of the portlet records is different for logged on users. It can take a value of either true or false. The default value for this tag is true.
<acceptContentType>	Specifies a comma delimited list of content types that the portlet can produce. For example, if a portlet can produce content of both HTML and MOBILEXML type, then the tag value is: text/html,text/vnd.oracle.mobilexml.
<hasShowLinkMode>	Indicates whether the portlet implements the Show Link show mode. If the value is false, the portlet uses its short or full title to display a link label that references the portlet content in a mobile device.  Otherwise, a customized link can be generated in the portlet code. The tag can take a value of either true or false. The default value for this tag is false.
<mobileOnly>	Indicates whether the portlet is available only to mobile devices. The tag can take a value of either true or false. The default value for this tag is false.
<preferenceStorePath>	Specifies the base preference store path where the provider has stored the portlet customization information. This path is used when exporting portlets.
<createdOn>	Defines the portlet creation date. The default value is sysdate.
<createdBy>	Defines the user who created the portlet record.
<lastUpdatedOn>	Defines the most recent date when the portlet record was changed. Defaults to sysdate.
<lastUpdatedBy>	Defines the user who most recently changed the portlet record.
<passAllUrlParams>	Indicates parameter passing behavior in the portlet. It can take a value of either true or false. If the tag value is true, then OracleAS Portal passes all parameters in the URL to the portlet. If the tag value is false, then the portlet receives only those parameteres that are intended for the portlet. The default value for this tag is true.
<cacheLevel>	Indicates a portlet's cache level. It can take one of the following values: wwpro_api_provider.CACHE_LEVEL_SYSTEM, wwpro_api_provider.CACHE_LEVEL_USER, wwpro_api_provider.CACHE_LEVEL_PTL_SESSION
<rewriteUrls>	Indicates whether or not URL rewriting will be performed on the output from a portlet render request. It can take a value of either true or false. The default value for this tag is false.