Unit 15.2. The Web Toolkit and Cookies

Three Cookie Actions

As a Web developer, there are three main actions you need to know in order to work with cookies; in fact, you will probably only use the first two:

OWA_COOKIE Package

Oracle provides a package, OWA_COOKIE, with procedures that allow you to perform each of these actions (Table 15.2). Other elements in the OWA_COOKIE package, such as the OWA_COOKIE type, provide additional built-in support for cookies.

HTTP Header

Cookies are sent (and removed) in the HTTP header.

To send and remove cookies, use the following syntax to open and then later close this HTTP header:

FOR EXAMPLE

							[procedure text goes here - no HTML generated] 
OWA_UTIL.mime_header(bclose_header=>FALSE); 
OWA_COOKIE.send('SESSION_ID', 572, sysdate+365); 
OWA_UTIL.http_header_close; 
  [generate any HTML here, after closing http header]
						

The HTTP header must be opened and closed before any htp procedures or functions are executed; that is, before any HTML is generated by the PL/SQL procedure. If not, then the cookie will not be sent/removed.

The OWA_UTIL.mime_header procedure actually takes several parameters (Table 15.3):

OWA_UTIL.mime_header(ccontent_type, bclose_header, ccharset); 

If you just want to read or “get” the value of a cookie, you do not need to worry about the HTTP header. It is not necessary to put the OWA_COOKIE.get procedure inside of an HTTP header.

Cookie Recipes

The best way to manage cookies is to write small procedures and functions that work with cookies. Whenever possible, create modular code that can be reused.

The next sections contain short procedures and functions to set a cookie, read a cookie value, read all cookie values, and check for a cookie. Once these are created, you can use these procedures and functions as needed throughout your site.

Set a Cookie: OWA_COOKIE.SEND

The following code sets a cookie for whatever name and value are passed in. The expiration date is optional. If it is supplied, the cookie will be set as a persistent cookie by the browser, with the expiration date supplied. If no expiration date is supplied, then the default value of NULL will be used, making it a session-level cookie. Session-level cookies cease to exist when the browser is closed.

FOR EXAMPLE

CREATE OR REPLACE PROCEDURE set_cookie 
     (p_cookie_name  IN VARCHAR2, 
      p_cookie_value IN VARCHAR2, 
      p_expires      IN DATE DEFAULT NULL) 
 IS 
BEGIN 
  OWA_UTIL.mime_header(bclose_header=>FALSE); 
  OWA_COOKIE.SEND(p_cookie_name, 
                  p_cookie_value, 
                  p_expires); 
  OWA_UTIL.http_header_close; 
END; 

Now any time that you need to set a cookie, call this procedure from PL/SQL— but only call it before any HTML has been generated by your PL/SQL procedure.

set_cookie('SESSION_ID','572'), 

To set a persistent cookie, supply an expiration date. The following call sets the cookie to expire in 5 days:

set_cookie('SESSION_ID','572',sysdate+5); 

Change a Cookie Value: OWA_COOKIE.SEND

To change a cookie value, use the same code that you would use to set the cookie. The name you supply should be the name of the cookie you want to change. Provide this name and the new value.

A cookie value can only be set from within the HTTP header, even if you are changing the value of an existing cookie. Again, the HTTP header must be opened and closed before any HTML is generated.

Read a Cookie Value: OWA_COOKIE.GET

The next function retrieves the value of a cookie with the name passed in. If no values are found, then the function returns a NULL value.

In the example below, note that a variable v_cookie is declared. This declaration is necessary because OWA_COOKIE.get is used to retrieve cookie values, and a container must exist to hold these returned values. The resulting cookie information must be stored in a variable of type OWA_COOKIE.cookie.

The OWA_COOKIE.cookie datatype is an array datatype. Any variable of type OWA_COOKIE.cookie has three characteristics.

NAME: The name of the cookie in the array.

NUM_VALS: The number of values stored in the array.

VALS(n): The nth value stored in the array. Unlike JavaScript arrays, this array starts with 1.

The syntax for these is demonstrated in the get_cookie function, below. This function is reusable. It has an IN parameter of a cookie name. The function checks for the existence of a cookie with the name that is passed in. If a cookie exists with that name, the procedure returns the cookie value. Otherwise, it returns a NULL value.

FOR EXAMPLE

CREATE OR REPLACE FUNCTION get_cookie 
   (p_cookie_name IN VARCHAR2) 
 RETURN VARCHAR2 
 IS 
    v_cookie     OWA_COOKIE.cookie; 
 BEGIN 
   v_cookie := OWA_COOKIE.GET(p_cookie_name); 
   IF v_cookie.num_vals != 0 THEN 
       RETURN v_cookie.vals(1); 
   ELSE 
       RETURN NULL; 
   END IF; 
END; 

Read All Cookie Values: OWA_COOKIE.GET_ALL

The OWA_COOKIE.get_all function retrieves all cookies. It has three out parameters. Two of them are arrays to hold the names and values of the cookies, since more than one cookie may be returned:

• NAMES: The name of each cookie in the array.

• VALS: The values of each cookie stored in the array.

• NUM_VALS: The total number of values stored in the array. This is an integer, not an array.

The syntax for using these parameters is demonstrated in the get_all_cookies procedure, below. It does not have an IN parameter of a cookie name, because it is retrieving all cookies, not a specific one. Arrays of type OWA_COOKIE.vc_arr are declared to hold the names and values of the cookies.

This procedure paints all cookie names and values to the screen, if any are found. Note that the step where cookie values are displayed to the screen is not typical cookie processing; normally, users would not see cookie values on the screen. Instead, cookie values would be used for other processing.

FOR EXAMPLE

CREATE OR REPLACE PROCEDURE get_all_cookies 
 IS 
    v_cookie_names  OWA_COOKIE.vc_arr; 
    v_cookie_values OWA_COOKIE.vc_arr; 
    v_cookie_count  INTEGER; 
 BEGIN 
   OWA_COOKIE.get_all(v_cookie_names, 
                      v_cookie_values, 
                      v_cookie_count); 
   htp.p('<HTML><BODY>'), 
   FOR num IN 1..v_cookie_count LOOP 
      htp.p('Cookie #'||num||': Name='|| 
             v_cookie_names(num)||', Value='|| 
             v_cookie_values(num)||'<BR>'), 
   END LOOP; 
   htp.p('</BODY></HTML>'), 
   EXCEPTION 
      WHEN OTHERS THEN 
      htp.p('Error in get_all_cookies: '||SQLERRM); 
END; 

Check Whether a Cookie Exists

Sometimes it is enough to know whether a cookie exists or not, without retrieving its value. The following function checks for the existence of a cookie with the name passed in. The function returns a TRUE value if cookie values are found. It returns FALSE if there are no values stored for the cookie.

FOR EXAMPLE

CREATE OR REPLACE FUNCTION cookie_exists 
    (p_cookie_name IN VARCHAR2) 
 RETURN BOOLEAN 
 IS 
   v_cookie OWA_COOKIE.COOKIE; 
BEGIN 
   v_cookie := OWA_COOKIE.GET(p_cookie_name); 
   IF v_cookie.num_vals != 0 THEN 
       RETURN TRUE; 
   ELSE 
       RETURN FALSE; 
   END IF; 
END; 

Unit 15.2 Exercises

15.2.1. Compile the Procedures

15.2.2. Collect Information for a Cookie

15.2.3. Set a Cookie

15.2.4. Check for the Existence of a Cookie

15.2.5. Retrieve and Display a Cookie Value

15.2.6. Retrieve and Display a Cookie Value

Unit 15.2 Exercise Answers

15.2.1. Answer

CREATE OR REPLACE PROCEDURE set_cookie 
     (p_cookie_name  IN VARCHAR2, 
      p_cookie_value IN VARCHAR2, 
      p_expires      IN DATE DEFAULT NULL) 
 IS 
BEGIN 
  OWA_UTIL.mime_header(bclose_header=>FALSE); 
  OWA_COOKIE.SEND(p_cookie_name, 
                  p_cookie_value, 
                  p_expires); 
  OWA_UTIL.http_header_close; 
END; 

CREATE OR REPLACE FUNCTION get_cookie 
   (p_cookie_name IN VARCHAR2) 
 RETURN VARCHAR2 
 IS 
    v_cookie     OWA_COOKIE.cookie; 
 BEGIN 
   v_cookie := OWA_COOKIE.GET(p_cookie_name); 
   IF v_cookie.num_vals != 0 THEN 
       RETURN v_cookie.vals(1); 
   ELSE 
       RETURN NULL; 
   END IF; 
END; 

CREATE OR REPLACE PROCEDURE get_all_cookies 
 IS 
    v_cookie_names  OWA_COOKIE.vc_arr; 
    v_cookie_values OWA_COOKIE.vc_arr; 
    v_cookie_count  INTEGER; 
 BEGIN 
   OWA_COOKIE.get_all(v_cookie_names, 
                      v_cookie_values, 
                      v_cookie_count); 
   htp.p('<HTML><BODY>'), 
   FOR num IN 1..v_cookie_count LOOP 
      htp.p('Cookie #'||num||': Name='|| 
             v_cookie_names(num)||', Value='|| 
             v_cookie_values(num)||'<BR>'), 
   END LOOP; 
   htp.p('</BODY></HTML>'), 
   EXCEPTION 
      WHEN OTHERS THEN 
      htp.p('Error in get_all_cookies: '||SQLERRM); 
END; 
CREATE OR REPLACE FUNCTION cookie_exists 
    (p_cookie_name IN VARCHAR2) 
 RETURN BOOLEAN 
 IS 
   v_cookie OWA_COOKIE.COOKIE; 
BEGIN 
   v_cookie := OWA_COOKIE.GET(p_cookie_name); 
   IF v_cookie.num_vals != 0 THEN 
       RETURN TRUE; 
   ELSE 
       RETURN FALSE; 
   END IF; 
END; 

15.2.2. Answer

CREATE OR REPLACE PROCEDURE VISITOR_NAME 
   IS 
BEGIN 
htp.p('<HTML> 
       <HEAD><TITLE>Name, Please</TITLE></HEAD> 
       <BODY> 
       <H1>What is Your Name?</H1> 
       <FORM NAME="visitor_name_form" 
             ACTION="process_visitor_name" 
             METHOD="POST"> 
       <INPUT NAME="p_visitor_name" TYPE="text" > 
       <INPUT TYPE="submit" VALUE="Save"> 
       </FORM> 
       </BODY> 
       </HTML>'), 
EXCEPTION 
    WHEN OTHERS THEN 
       htp.p('An error occurred in VISITOR_NAME: ' 
             ||SQLERRM); 
END; 

15.2.3. Answer

CREATE OR REPLACE PROCEDURE PROCESS_VISITOR_NAME 
   (p_visitor_name IN VARCHAR2) 
   IS 
BEGIN 
    set_cookie('VISITOR',p_visitor_name); 
    htp.p('<HTML> 
           <HEAD><TITLE>Thank You</TITLE></HEAD> 
           <BODY> 
           Click <A HREF="main_frame">here</A> to 
           enter the application. 
           </BODY> 
           </HTML>'), 
EXCEPTION 
    WHEN OTHERS THEN 
        htp.p('An error occurred in 
        PROCESS_VISITOR_NAME: '||SQLERRM); 
END; 

15.2.4. Answer

CREATE OR REPLACE PROCEDURE MAIN_FRAME AS 
    v_val VARCHAR2(100); 
BEGIN 
IF cookie_exists('VISITOR') THEN 
htp.p(' 
<HTML> 
<HEAD> 
<TITLE>University Maintenance Website 
</TITLE> 
</HEAD> 
<FRAMESET ROWS="133,*"> 
  <FRAME NAME="top" SCROLLING="no" NORESIZE 
         TARGET="main" SRC="top_menu"> 
  <FRAME NAME="main" SRC="splash" TARGET="main"> 
  <NOFRAMES> 
    <BODY> 
    <P>This page uses frames, but your browser doesn''t 
support them. </P> 
    </BODY> 
   </NOFRAMES> 
</FRAMESET> 
</HTML> 
'), 
ELSE
											htp.script('document.location="visitor_name";'),
											END IF; 
END; 

15.2.5. Answer

CREATE OR REPLACE PROCEDURE TOP_MENU AS 
    v_visitor  VARCHAR2(100); 
 BEGIN 
    v_visitor := get_cookie('VISITOR'), 
    htp.p(' 
    <HTML> 
    <HEAD> 
    <TITLE>University Maintenance Website 
    </TITLE> 
    </HEAD> 
    <BODY BGCOLOR="#99CCFF"> 
    '), 
    htp.p(' 
    <P ALIGN="center"> 
    <FONT FACE="Arial" SIZE=5 >University Maintenance Website for
											'||v_visitor||'</FONT></P> 
    <P ALIGN="right">If you are not '||v_visitor||', click <A
											HREF="visitor_name" TARGET="_top">here</A></P> 
    '), 

    htp.p(' 
    <TABLE BORDER="0" WIDTH="100%"> 
    <TR> 
    <TD ALIGN="center"><A HREF="students_frame" TARGET="main"><FONT 
    FACE="Arial">Students</FONT></A></TD> 
    <TD ALIGN="center"><A HREF="instructors_frame" 
    TARGET="main"><FONT FACE="Arial">Instructors</FONT></A></TD> 
    <TD ALIGN="center"><A HREF="classes_frame" TARGET="main"><FONT 
    face="Arial">Classes</FONT></A></TD> 
    </TR> 
    </TABLE> 
    </BODY> 
    </HTML> 
    '), 
END; 

15.2.6. Answer

CREATE OR REPLACE PROCEDURE PROCESS_VISITOR_NAME 
   (p_visitor_name IN VARCHAR2) 
   IS 
BEGIN 
    set_cookie('VISITOR', 
               p_visitor_name, 
               sysdate+5); 
    htp.p('<HTML> 
           <HEAD><TITLE>Thank You</TITLE></HEAD> 
           <BODY> 
           Click <A HREF="main_frame">here</A> to 
           enter the application. 
           </BODY> 
           </HTML>'), 
EXCEPTION 
    WHEN OTHERS THEN 
        htp.p('An error occurred in 
        PROCESS_VISITOR_NAME: '||SQLERRM); 
END;