13 Searching Portal Content

13.4.1 Creating a Directory for the XML File

If you decide to transform your search results into an XML file, you must first perform some set up tasks to define the physical directory in which to write the file.

To create a directory on the OracleAS Portal middle tier:

1. In SQL*Plus, connect as SYSTEM or SYS and enter the following command:

   create directory <dirname> as '<physical_location>';
   
   

   For example:

   create directory RESULTDIR as '/u02/ora/OraHome_101202_PortalMF/Apache/Apache/htdocs/searchapi';
   
   

   In this example, we use the htdocs directory of the OracleAS Portal middle tier. This is a good location to use as you can then access the XML results file through HTTP, in the format:

   http://<Portal_Mid_Tier>:<Port>/<directory>/<XML_Output_File>
   
   

   For example:

   http://my.portal.com:7778/searchapi/results.xml
   
   

   You can then use this to specify the XML file as the data source for OmniPortlet. For an example of how to do this, refer to Section 13.5.1, "Displaying XML Search Results in OmniPortlet".

2. Still in SQL*Plus, grant write privileges to the directory from PL/SQL programs. In our example, we would do this by entering the following command:

   grant write on directory RESULTDIR to public;
   
   

3. Check that you can write files to the new directory by running the following procedure:

   declare
    2 v_output_file1 utl_file.file_type;
    3 begin
    4 v_output_file1 := utl_file.fopen('RESULTDIR', 'NEW.txt', 'a');
    5 utl_file.put_line(v_output_file1, 'NATURE and Beauty');
    6 utl_file.fclose_all;
    7 end;
    8 /
   
   PL/SQL procedure successfully completed.
   
   

   Now, when you go to the directory on the file system, you should see the NEW.txt file.

13.4.2 Creating an XML File from a CLOB

When you have specified the location for the XML output, you can write the procedure that creates it. Example 13-4 shows a generic procedure that takes the CLOB produced by the get_all_items_xml API and writes an XML file to a specific location. It takes two input parameters: the file name and the CLOB.

create or replace procedure results_xml_to_file(xml_filename varchar2, result_xml clob) as
  l_amount binary_integer;
  l_offset number := 1;
  l_text   varchar2(32767);
  l_file   utl_file.file_type;
  l_clob   clob;
begin
  l_clob := result_xml;
  l_file := utl_file.fopen(
    location  => 'RESULTDIR', -- Directory name is case-sensitive.
    filename  => xml_filename,
    open_mode => 'w'
  );
  l_amount := 32767;
  l_offset := 1;
  begin
    dbms_lob.open(l_clob, dbms_lob.file_readonly);
    loop
      dbms_lob.read(l_clob, l_amount, l_offset, l_text);
      utl_file.put(
        file   => l_file,
        buffer => l_text
      );
      l_offset := l_offset + l_amount;
      exit when l_amount < 32767;
    end loop;
    utl_file.new_line(file => l_file);
    dbms_lob.close(l_clob);
  end;
  utl_file.fclose(file => l_file);
exception
  ...
end;
/

13.4.3 Generating Search Results in XML

Now, when you use the APIs to produce search results as XML, you can call the procedure in Example 13-4 to write the resulting CLOB to an XML file on the file system. Example 13-5 shows how you might do this.

declare
  l_results   wwsrc_api.items_result_array_type;
  l_scores    wwsrc_api.number_list_type;
  l_count     number;
  l_clob      clob;
begin
  l_results := wwsrc_api.item_search(
    p_mainsearch => 'portal',
    p_out_count  => l_count,
    p_out_scores => l_scores
  );
  l_clob := wwsrc_api.get_all_items_xml(l_results);
  results_xml_to_file('results12.xml', l_clob);
exception
  ...
end;
/

For information about the item_search API used inExample 13-5, refer to Section 13.1, "Searching For Items Across All Page Groups".

You can use the XML file generated by this API as a data source for OmniPortlet. For an example of how you might do this, refer to Section 13.5.1, "Displaying XML Search Results in OmniPortlet".

13.4.4 Workaround for get_item_xml

When you use get_item_xml to transform search results to XML, the API produces a <?xml version="1.0" ?> element for each search result. This produces invalid XML. Example 13-6 shows a workaround that removes these tags and also adds opening and closing <ResultSet> tags to produce an XML file with the ROWSET/ROW structure. If you want to use the XML file as a data source for OmniPortlet, you should do something similar.

declare
  l_amount    binary_integer;
  l_offset    number       := 1;
  l_text      varchar2(32767);
  l_file      utl_file.file_type;
  l_clob      clob;
  l_results   wwsrc_api.items_result_array_type;
  l_scores    wwsrc_api.number_list_type;
  l_count     number;
begin
  l_results := wwsrc_api.item_search(
    p_mainsearch => 'portal',
    p_out_count  => l_count,
    p_out_scores => l_scores
  );
  l_file := utl_file.fopen(
    location  => 'RESULTDIR', -- Directory name is case-sensitive.
    filename  => 'results14.xml',
    open_mode => 'w'
  );
  utl_file.put(
    file   => l_file,
    buffer => '<ResultSet>'
  );
    for i in 1..l_results.count loop
      l_amount := 32767;
      l_offset := 1;
    begin
      l_clob := wwsrc_api.get_item_xml(l_results(i));
      dbms_lob.open(l_clob, dbms_lob.file_readonly);
    loop
      dbms_lob.read(l_clob, l_amount, l_offset, l_text);
      -- Workaround for XML generated with get_item_xml.
      if instr(l_text, '?>') != 0 then
        l_text := substr(l_text, instr(l_text, '?>') + 2);
      end if;
      -- End of workaround.
      utl_file.put(
        file   => l_file,
        buffer => l_text
      );
      l_offset := l_offset + l_amount;
      exit when l_amount < 32767;
    end loop;
    utl_file.new_line(file => l_file);
    dbms_lob.close(l_clob);
    end;
    end loop;
    utl_file.put(
      file   => l_file,
      buffer => '</ResultSet>'
    );
    utl_file.fclose(file => l_file);
exception
  ...
end;
/

13.5.1 Displaying XML Search Results in OmniPortlet

The following steps provide an example of how to use the XML generated by the search APIs as the data source for OmniPortlet. For example, you could schedule a job to regularly execute an API to produce search results as XML and then automatically display those results in an OmniPortlet.

For more information about OmniPortlet, refer to the Oracle Application Server Portal Developer's Guide.

1. First you need to add a new OmniPortlet instance to a page.

   
   

   Tip: OmniPortlet is usually available in the Portlet Builders area of the Portlet Repository.

   
   

2. Click the Define link to launch the OmniPortlet Wizard.

3. On the Type page of the wizard, select XML, then click Next.

4. On the Source page, in the XML URL field, enter the URL of your XML file, for example:

   http://my.portal.com:7778/searchapi/results.xml
   
   

   Because the XML data produced by the search APIs uses a ROWSET/ROW structure, you do not need to specify an XSL filter.

5. Click Next.

6. On the View page, select Tabular for the Layout Style, then click Next.

7. On the Layout page, choose the columns you want to display in the portlet and how you want them to appear.

8. Click Finish to create the OmniPortlet instance.

13.5.2 Displaying Search Results in a Dynamic Page

The following two examples show how to display search results in a dynamic page portlet. Users can then add this portlet to any page within your portal.

1. Create a procedure that the dynamic page can call to perform the search.

   The procedure in Example 13-7 uses the item_search API to search for a specified term (searchterm) and displays only those results with a score higher than a specified value (score).

   
   

   Note: You must create the procedure in the database in which your portal resides.

   
   

   Example 13-7 Procedure to Perform the Search

   create or replace procedure search_results(searchterm varchar2, score number) as
     x varchar2(100);
     y number;
     l_results   wwsrc_api.items_result_array_type;
     l_count     number;
     l_scores    wwsrc_api.number_list_type;
   begin
     x := searchterm;
     y := score;
     l_results := wwsrc_api.item_search(
       p_mainsearch => x,
       p_out_count  => l_count,
       p_out_scores => l_scores
     );
     htp.p('Number of total hits: ' || l_count);
     htp.p('<br>');
     htp.p('<br>');
     for i in 1..l_results.count loop
       if (l_scores(i) > y) then
         htp.p('<b>' || i || '</b> - <a href="' || l_results(i).url ||
           '">' || l_results(i).display_name || '</a>');
         htp.p('<br>');
         htp.p('score = ' || l_scores(i));
         htp.p('<br>');
       end if;
     end loop;
   exception
     ...
   end;
   /
   grant execute on search_results to public;
   
   

   For information about the item_search API used inExample 13-7, refer to Section 13.1, "Searching For Items Across All Page Groups".

2. Create the dynamic page.

   A dynamic page is one of the portlets you can build using the OracleAS Portal Portlet Builder. For more information about Portlet Builder, refer to the Oracle Application Server Portal Developer's Guide. For more information about building dynamic pages, refer to the OracleAS Portal online Help.

   Example 13-8 shows the code to use for the dynamic page.

   
   

   Tip: Replace <schema> with the name of the schema in which you created your procedure.

   
   

   Example 13-8 Code for Dynamic Page to Display Results

   <html>
     <head>
       <title>Example for Search API UI</title>
     </head>
     <body>
       <h2>My Search Form</h2>
       <oracle>
         declare
           x varchar2(100);
           y number;
         begin
           x := :searchterm;
           y := :score;
           <schema>.search_results(x,y);
         end;
       </oracle>
     </body>
   </html>
   
   

3. Provide default values for the two bind variables defined in the HTML code so that the dynamic page displays some results (Figure 13-1).

   Figure 13-1 Providing Default Values for Bind Variables

   
   Description of "Figure 13-1 Providing Default Values for Bind Variables"
   
   

4. Make sure the dynamic page is available as a portlet.

5. You can now add this dynamic page portlet to any page in your portal.

   
   

   Tip: You should find the portlet in the Staging Area of the Portlet Repository under the name of the provider in which you created it.

   
   

   Figure 13-2 Default Search Results Displayed in the Dynamic Page Portlet

   
   Description of "Figure 13-2 Default Search Results Displayed in the Dynamic Page Portlet"
   
   

   The dynamic page portlet displays search results based on the default values provided when you created the dynamic page.

6. Users can personalize this portlet to provide their own search term and minimum score.

   Figure 13-3 Personalizing Search Criteria

   
   Description of "Figure 13-3 Personalizing Search Criteria"
   
   

   In Figure 13-4 you can see the changes in the search results when a user personalizes the portlet and changes the minimum score to 70.

   Figure 13-4 Personalized Search Results Displayed in the Dynamic Page Portlet

   
   Description of "Figure 13-4 Personalized Search Results Displayed in the Dynamic Page Portlet"