The Package Specification

The specification of a package lists all the elements in that package that are available for use in applications, and provides all the information a developer needs in order to use elements defined in the package (often referred to as an "API" or Application Programming Interface). A developer should never have to look at the implementation code in a package body to figure out how to use an element in the specification.

Here are some rules to keep in mind for package specification construction:

· You can declarevariables and constants of almost any datatype, such as numbers, strings, and collections, at the package level (i.e., not within a particular procedure or function in the package). This is referred to as package-level data; generally, you should avoid declaring variables in the package specification, although constants are always "safe."

You cannot declare cursor variables (variables defined from a REF CURSOR type) in a package specification (or body). Cursor variables are not allowed to persist at the session level (see Section 17.4 for more information about package data persistence).

· You can declare almost any type of data structure, such as a collection type, a record type, or a REF CURSOR type.

· You can declareprocedures and functions in a package specification, but you can include only the header of the program (everything up to but not including the IS or AS keyword).

· You can include explicit cursors in the package specification. An explicit cursor can take one of two forms: it can include the SQL query as a part of the cursor declaration, or you can "hide" the query inside the package body and provide only a RETURN clause in the cursor declaration. This topic is covered in more detail in Section 17.4.3.2.

· If you declare any procedures or functions in the package specification or if you declare a CURSOR without its query, then you must provide a package body in order to implement those code elements.

· You can include an AUTHID clause in a package specification, which determines whether any references to data objects will be resolved according to the privileges of the owner of the package (AUTHID DEFINER) or of the invoker of the package (AUTHID CURRENT_USER). See Chapter 20 for more information on this feature.

· You can include an optional package name label after the END statement of the package, as in:

END my_package;

Here is a very simple package specification illustrating these rules:

1 CREATE OR REPLACE PACKAGE favorites_pkg 2 AUTHID CURRENT_USER 3 IS 4 -- Two constants; notice that I give understandable 5 -- names to otherwise obscure values. 6 7 c_chocolate CONSTANT PLS_INTEGER:= 16; 8 c_strawberry CONSTANT PLS_INTEGER:= 29; 9 10 -- A nested table TYPE declaration11 TYPE codes_nt IS TABLE OF INTEGER;12 13 -- A nested table declared from the generic type.14 my_favorites codes_nt;15 16 -- A REF CURSOR returning favorites information.17 TYPE fav_info_rct IS REF CURSOR RETURN favorites%ROWTYPE;18 19 -- A procedure that accepts a list of favorites20 -- (using a type defined above) and displays the21 -- favorite information from that list.22 PROCEDURE show_favorites (list_in IN codes_nt);23 24 -- A function that returns all the information in25 -- the favorites table about the most popular item.26 FUNCTION most_popular RETURN fav_info_rct;27 28 END favorites_pkg; -- End label for package

As you can see, a package specification is, in structure, essentially the same as a declaration section of a PL/SQL block. One difference, however, is that a package specification may not contain any implementation code.