PL/SQL Index-by Tables Sample Application Readme

Table of Contents  

1. Introduction

1.1 Pre-requisite

The user is expected to have technical knowledge in the following areas,

  • JDBC
  • Oracle10g Database
  • 1.2 Technical Overview

    Array processing is a common need in procedural languages. Index-By Tables are one of the collections provided by PL/SQL to store arrays, lists and trees. They are similar to one-dimensional arrays and are referenced like arrays of records. Since Index-By tables can be passed as parameters, they can be used to move columns of data into and out of database tables or between client-side applications and stored subprograms.

    Index-by tables are smilar to nested tables. They have the same structure, and their individual elements are accessed in the same way (using subscript notation). The main difference is that nested tables can be stored in a database column (hence the term "nested table") but index-by tables cannot.

    Index-By tables can be created using any of the standard PL/SQL datatypes. To use an Index-By table, a datatype for the table must first be defined. Any built-in datatype or user-defined datatype can be specified when the datatype is defined. But Index-By tables cannot contain a table or a record with composite fields. The INDEX BY BINARY_INTEGER clause is required in all Index-By table definitions. When the table variable is declared, it can be referenced like an array by specifying an index value in parentheses to represent an element in the table. Elements of Index-By tables are initialized with null values automatically during declaration.

    2. Application Overview

    The sample application displays the city details including city id, city name, population and language spoken by majority of the people in the city.  A user can either Add or Delete a city detail to or from the database. The table in the database is populated by temporary values present in the array using PL/SQL Index-By table at a bulk. All the details of the city are retrieved from the database as a bulk and stored in the PL/SQL Index-By table.  

    3. Application Design  

        1.1 Design Notes

    The PL/SQL Index-By table is useful when the data from a single dimensional array has to be stored into and to be retrieved from the database as an array, in a bulk. The sample application is designed to store the city details available in different arrays in to the database, and also to display the city details by retrieveing them into arrays. The class PlsqlTablesSample implements the methods to store and retrieve arrays to and from the tables using JDBC API's. The method populateCityInfo inserts the array data in to CITY_TAB table by calling cityinfo_pkg.populate_DB stored procedure. The method displayCities calls the cityinfo_pkg.retrieve_All_Cities stored procudure to retrieve the values from the table into a set of arrays and displays to the user.

        1.2 Code Support

    Here is the code explaining retrieving PL/SQL Index By table OUT parameter. You can find more details of the code in PlsqlTablesSample.java file under src\oracle\otnsamples\jdbc folder. Look into Description of Sample Files section for folder and file details.
    ...    
    // Create a Callable statement object and cast it
    ocstmt =(OracleCallableStatement)conn.prepareCall(
    " begin"+
    " cityinfo_pkg.populate_Index_By_tbl();"+
    " cityinfo_pkg.retrieve_All_Cities(?,?,?,?);"+
    " end;");
    // Index-By Table can be registered using registerIndexTableOutParameter
    ocstmt.registerIndexTableOutParameter(1,maxTablLen,OracleTypes.INTEGER,0);

    // Register the out parameter of the index by table for the 2nd parameter
    // It returns an array of city names in the form of string
    ocstmt.registerIndexTableOutParameter(2,maxTablLen,OracleTypes.VARCHAR,eleMaxLen);

    // Register the out parameter of the index by table for the 3rd parameter
    // It contains an array of population corresponding to each city
    ocstmt.registerIndexTableOutParameter(3,maxTablLen,OracleTypes.INTEGER,eleMaxLen);

    // Register the out parameter of the index by table for the 4th parameter
    ocstmt.registerIndexTableOutParameter(4,maxTablLen,OracleTypes.VARCHAR,eleMaxLen);

    // Execute the callable statement.
    ocstmt.execute();

    // Index By Table sent as OUT parameter of a procedure can be retrieved
    // as Java primitive array using
    // synchronized public Object getPlsqlIndexTable
    // (int paramIndex, Class primitiveType) throws SQLException
    // where paramIndex is the index of the OUT parameter and
    // primitiveType - Class of the OUT parameter datatype in java
    cityIdArray = (int[]) ocstmt.getPlsqlIndexTable(1,java.lang.Integer.TYPE);

    // Retrieve the array of name of the cities present in Index-by table
    cityNameArray = (String[]) ocstmt.getPlsqlIndexTable(2);

    // Retrieve the population of the cities present as integer in
    // index-by table
    populationArray = (int[]) ocstmt.getPlsqlIndexTable(3,java.lang.Integer.TYPE);
    ....


    4.Sample Application Files

    4.1 Readme/Install files and Stylesheets

    File

    Description

    readme.html

    This file.

    install.html Sample installation document
    envsetup.html Environment variable set up readme file.

    otn.css

    Style sheet used in the readme document.

    4.2 Application files

    The following Java source files are available under src\oracle\otnsamples\jdbc directory.

    File

    Description

    PlsqlTablesSample.java

    The Source file for the Sample

    PlsqlTablesFrame.java

    The Source file for the sample User Interface

    CityFrame.java This file contains the User Interface for adding City details
    GenTableModel.java The source file for the GenTableModel class, which  handles the JTable data.

    4.3 Configuration and Batch files

    File

    Description

    run.bat

    The batch file to compile and run the sample in Windows environment

    run.sh

    The shell script file to compile and run the sample in Linux environment

    PlsqlTablesSample.sql This file creates the package, tables and sequence required by the sample
    Connection.properties This file has the details of the database connection parameters

    5. Setting up the Sample Application

    For setting up and running the application please refer to the installation document.

    6. Additional Resources

    We hope you find this README file helpful. Please enter your comments about this sample in the OTN Sample Code Discussion Forum.

    E-mail this page
    Printer View Printer View
    Oracle Is The Information Company About Oracle | Oracle RSS Feeds | Careers | Contact Us | Site Maps | Legal Notices | Terms of Use | Privacy