Object Type wwsto_api_session

This object type provides access to a server-side, session-based, storage mechanism that can be used to store small amounts of information for short durations of time. When the user's session ends, this information is automatically removed from the system.

Note: It is recommended that provider implementations do not exist in the same schema as Oracle Portal. Therefore, calls to load_session and drop_session methods must be prefixed by the Oracle Portal owner schema, portal30.wwsto_api_session.load_session. The Portal owner schema must also be prefixed whenever a session object is defined, for example, l_user_obj portal30.wwsto_api_session.

A session is an uninterrupted connection between a browser and Oracle Portal, from initial access to log off or disconnect. The session is established as a public session upon initial access. It becomes an authenticated session at login.

Session storage

Server-side session storage reduces the need to use client-side mechanisms such as browser cookies or hidden HTML form fields to store this type of information.

Session storage allows you to:

• Store a value from one browser request and retrieve it in another request.

• Pass data across separate application pages.

• Store multiple values in different datatypes.

• Handle large numbers of users while avoiding naming conflicts.

Every user logged in to an application created with Oracle Portal has a private session storage area that is completely secure and isolated from other users.

Session object

The session object is the unit of session storage for an application working in Oracle Portal. Developers may access this object to access and manipulate temporary data for the session the user is currently running.

Working with the session object

The general procedure for working with the session object is:

1. Load the session object, with an appropriate domain and sub-domain combination, using the load_session method.

2. Manipulate the content of the object using the set_attribute methods, or just access its content using the get_attribute methods.

3. Force these changes to be saved, using the save_session method.

Typically this sequence occurs within the scope of one client routine that extracts and/or sets all of the client states. For example:

 declare
     l_store portal30.wwsto_api_session;
     l_date date;
 begin
    l_store := portal30.wwsto_api_session.load_session ('PORTAL', 'TEST');
    l_store.set_attribute ('LAST_ACCESSED', sysdate);
    l_store.set_attribute ('USERNAME', 'SMITH');
    l_store.set_attribute ('COUNRTY_CODE', 1);
    l_store.set_attribute ('LOCATION', 'US');
    l_store.set_attribute ('LAST_LOGGED_ON', sysdate);
    l_store.set_attribute_as_string
        ('OFFICE_LOCATION', 'CALIFORNIA', 'US', 'STRING');
    l_store.save_session;
 end;
 

The login session that creates the session storage object is defined by wwctx_api.get_sessionid.

Access to the data

Attribute values within a session are stored in native form. For example, the attribute may have been defined to use the logical type CURRENCY, which has a native implementation type of NUMBER.

Functions within the session storage object permit setting and returning attribute values in either native form or in a string representation of the logical type.

The session storage methods access all of the functionality of the session storage object. These methods take the case-insensitive name of the attribute to set or get the perform the required action.

The session storage methods access all of the functionality of the session storage object. These methods take the case-insensitive name of the attribute to perform the required action.

      l_session.set_attribute ('testDate', sysdate);
      dbms_output.put_line (l_session.get_attribute_as_date ('TeStDaTe'));
 

Security

Data in the session store is visible to all code that executes during a user's session. This includes Oracle Portal internal code as well as plug-in modules such as a provider or the methods of a customer application. Due to the potential visibility to other code that might run during the user's session, data meant to be secure should not be stored in session storage.

Session visibility

The storage allocated by a session storage object is visible only within the scope of the login session that created it. Therefore, it is not possible for multiple users to share the same session, or for a single user operating multiple login sessions to access sessions across the login session boundary.

Data consistency

New or modified elements of the session storage are cached in memory until the save_session method is called. As a result, it is possible for a browser performing multiple simultaneous actions to see an inconsistent view of the data in session storage.

Session storage objects should be saved frequently. To guarantee consistency of the data, clients should re-load the session after every save. In addition, a save should be performed immediately after session attributes are created/modified.

Lifetime of the session

After creation, sessions exist until they are explicitly dropped by calling the drop_session method, or are implicitly dropped because the user logged off the system (either explicitly or implicitly).

It is the responsibility of the callers of the session storage object to ensure that any critical data is copied to more permanent storage before the session is removed.

Transactional behavior

Session storage uses the callers transaction scope to perform all loading and saving operations.

Scope:

Public

Since:

Oracle Portal 3.0.6.6.5

_domain

_domain varchar2(30)

_element_data

_element_data wwsto_session_elements

_id

_id integer

_session_id

_session_id integer

_sub_domain

_sub_domain varchar2(200)

drop_session

static procedure drop_session(
    p_domain in varchar2,
    p_sub_domain in varchar2
) 

Removes the content of a session store object.

Note: Calls to this API must be prefixed by the Oracle Portal owner schema, for example, PORTAL30.

Example

    l_user_obj.drop_session
    (
        p_domain     => 'PORTAL',
        p_sub_domain => 'TEST'
    );
 

Parameters:

p_domain - the domain name for the session store object

p_sub_domain - the subdomain name for the session store object

Since:

Oracle Portal 3.0.6.6.5

dump_session

member procedure dump_session

Dumps the content of a session store object to an output buffer.

Note: The output of this function is intended for debugging purposes only and is not guaranteed to be in any version of the product.

Example

   l_user_obj.dump_session;
 

Since:

Oracle Portal 3.0.6.6.5

get_attribute_as_date

member function get_attribute_as_date(
    p_name in varchar2
) return date

Returns the value of a date attribute.

Example

     l_last_accessed := l_user_obj.get_attribute_as_date
     (
         p_name => 'LAST_ACCESSED'
     );
 

Parameters:

p_name - the name of the attribute

Returns:

the date value of an attribute, or null if the specified attribute does not exist

Exceptions:

VALUE_ERROR - if the attribute's type indicates that the implementation type is not a date

Since:

Oracle Portal 3.0.6.6.5

get_attribute_as_number

member function get_attribute_as_number(
    p_name in varchar2
) return number

Returns the value of a numeric attribute.

Example

 l_number_attr := l_user_obj.get_attribute_as_number
 (
     p_name => 'FINAL_VALUE'
 );
 

Parameters:

p_name - the name of the attribute

Returns:

the number value of an attribute, or null if the specified attribute is not found

Exceptions:

VALUE_ERROR - if the attribute's type indicates that the implementation type is not a number

Since:

Oracle Portal 3.0.6.6.5

get_attribute_as_string

member function get_attribute_as_string(
    p_name in varchar2,
    p_language in varchar2,
    p_type_name in varchar2 default 'string'
) return varchar2

Returns the value of a string attribute.

Gets the value of the attribute, represented as a type-specific, NLS formatted string. This function returns the value of the specified attribute as a text string. The text string is obtained by calling the attribute's type handling object to convert it from its native form into a string form.

Note: The attribute type may have performed extensive transformation on the data value before returning it.

Example

   l_color := l_user_obj.get_attribute_as_string
   (
       p_name     => 'BGCOLOR',
       p_language => wwnls_api.AMERICAN
   );
 

Parameters:

p_name - the name of the attribute

p_language - the language to be used for all value transformations

p_type_name - the name of the datatype. The default is 'STRING'.

Returns:

the text string version of the attribute value, transformed according to a set of rules defined against the attribute's type, or null if not found

Exceptions:

VALUE_ERROR - if the attribute's type indicates that the implementation type is not a string

Since:

Oracle Portal 3.0.6.6.5

get_attribute_as_varchar2

member function get_attribute_as_varchar2(
    p_name in varchar2
) return varchar2

Returns the value of a varchar2 attribute.

Example

   l_name_attr := l_user_obj.get_attribute_as_varchar2
   (
       p_name => 'Portal'
   );
 

Parameters:

p_name - the name of the attribute

Returns:

the varchar2 value of an attribute, or null if the specified attribute does not exist

Exceptions:

VALUE_ERROR - if the attribute's type indicates that the implementation type is not a varchar2

Since:

Oracle Portal 3.0.6.6.5

get_attribute_index

member function get_attribute_index(
    p_name in varchar2
) return integer

Get the index of a particular attribute in the internal storage structure. This function is not intended, nor supported, in customer code.

Parameters:

p_name - the name of the attribute within the block

Returns:

the index or null if not found

get_domain

member function get_domain
return varchar2

Returns the domain of a session store object.

Example

     l_domain := l_user_obj.get_domain;
 

Returns:

a domain name

Since:

Oracle Portal 3.0.6.6.5

get_sub_domain

member function get_sub_domain
return varchar2

Returns the subdomain of a session store object.

Example

      l_sub_domain := l_user_obj.get_sub_domain;
 

Returns:

a subdomain name

Since:

Oracle Portal 3.0.6.6.5

is_empty

member function is_empty
return boolean

Is this session store object empty? See load_session for when an empty session store object is created.

Example

       l_empty_session := l_user_obj.is_empty;
 

Since:

Oracle Portal 9.0.2.6

load_session

static function load_session(
    p_domain in varchar2,
    p_sub_domain in varchar2
) return wwsto_api_session

Loads and then returns a copy of a session store object.

Storage is located by the combination of the domain and subdomain parameters, and the Login session ID.

If a session store object has not previously been created for this combination of domain, sub-domain, and session ID, then an empty session store object is created and returned.

Note: As this function returns a copy of the data, it is possible to call load_session twice and have two independent copies of the data. The outcome of simultaneously operating on two copies of the same data is not defined.

Example

It is recommended that the provider implementation does not exist in the same schema as Oracle Portal. Therefore, calls to wwsto_api_session methods must be prefixed by the Oracle Portal owner schema, for example, PORTAL30.

 declare
     l_user_obj portal30.wwsto_api_session;
 begin
     l_user_obj := portal30.wwsto_api_session.load_session
     (
         p_domain     => 'PORTAL',
         p_sub_domain => 'TEST'
     );
     l_user_obj.save_session;
 end;
 

Parameters:

p_domain - the domain name for the session store object

p_sub_domain - the sub-domain for the session store object

Returns:

a session store object to manipulate

Since:

Oracle Portal 3.0.6.6.5

save_session

member procedure save_session

Saves session data. Session data is saved persistently and if the session data did not previously exist, it is created at this time.

Note: Data changes may not be preserved until this procedure is called.

Example

     l_user_obj.save_session;
 

Since:

Oracle Portal 3.0.6.6.5

set_attribute

member procedure set_attribute(
    p_name in varchar2,
    p_value in date
) 

Sets the date value of an attribute.

Example

It is recommended that the provider implementation does not exist in the same schema as Oracle Portal. Therefore, calls to wwsto_api_session methods must be prefixed by the Oracle Portal owner schema, for example, PORTAL30.

   declare
     l_user_obj portal30.wwsto_api_session;
   begin
     l_user_obj := portal30.wwsto_api_session.load_session
     (
         p_domain      => 'PORTAL',
         p_sub_domain  => 'TEST'
     );

     l_user_obj.set_attribute
     (
         p_name  => 'LAST_LOGGED_ON',
         p_value => sysdate
     );

     l_user_obj.save_session;
   end;
 

Parameters:

p_name - the name of the attribute

p_value - the value to be stored

Exceptions:

VALUE_ERROR - if the attribute's type indicates that the implementation type is not a DATE column

Since:

Oracle Portal 3.0.6.6.5

set_attribute

member procedure set_attribute(
    p_name in varchar2,
    p_value in number
) 

Sets the numeric value of an attribute.

Example

It is recommended that the provider implementation does not exist in the same schema as Oracle Portal. Therefore, calls to wwsto_api_session methods must be prefixed by the Oracle Portal owner schema, for example, PORTAL30.

 declare
   l_user_obj portal30.wwsto_api_session;
 begin
   l_user_obj := portal30.wwsto_api_session.load_session
   (
       p_domain     => 'PORTAL',
       p_sub_domain => 'TEST'
   );

   l_user_obj.set_attribute
   (
       p_name  => 'COUNTRY_CODE',
       p_value => 1
   );

   l_user_obj.save_session;
 end;
 

Parameters:

p_name - the name of the attribute

p_value - the value to be stored

Exceptions:

VALUE_ERROR - if the attribute's type indicates that the implementation type is not a NUMBER column

Since:

Oracle Portal 3.0.6.6.5

set_attribute

member procedure set_attribute(
    p_name in varchar2,
    p_value in varchar2
) 

Sets the varchar2 value of an attribute.

Example

It is recommended that the provider implementation does not exist in the same schema as Oracle Portal. Therefore, calls to wwsto_api_session methods must be prefixed by the Oracle Portal owner schema, for example, PORTAL30.

   declare
   l_user_obj portal30.wwsto_api_session;
   begin
       l_user_obj := portal30.wwsto_api_session.load_session
       (
          p_domain     => 'PORTAL',
          p_sub_domain => 'TEST'
       );

       l_user_obj.set_attribute
       (
           p_name  => 'USERNAME',
           p_value => 'USER1'
       );

       l_user_obj.save_session;
   end;
 

Parameters:

p_name - the name of the attribute

p_value - the value to be stored

Exceptions:

VALUE_ERROR - if the attribute's type indicates that the implementation type is not a VARCHAR2 column

Since:

Oracle Portal 3.0.6.6.5

set_attribute_as_string

member procedure set_attribute_as_string(
    p_name in varchar2,
    p_value in varchar2,
    p_language in varchar2,
    p_type_name in varchar2 default 'string'
) 

Call this procedure to set the value of the attribute given a type-specific, NLS formatted string. The text string is transformed (internally) into the native form by calling upon the attribute's type handling object. The native form is then stored.

The attribute type may have performed extensive transformation on the text string before returning it as a native type.

Example

It is recommended that the provider implementation does not exist in the same schema as Oracle Portal. Therefore, calls to wwsto_api_session methods must be prefixed by the Oracle Portal owner schema, for example, PORTAL30.

   declare
   l_user_obj portal30.wwsto_api_session;
   begin
       l_user_obj := portal30.wwsto_api_session.load_session
       (
           p_domain     => 'PORTAL',
           p_sub_domain => 'TEST'
       );
       l_user_obj.set_attribute_as_string
       (
           p_name     => 'BGCOLOR',
           p_value    => 23,
           p_language => wwnls_api.AMERICAN
       );
       l_user_obj.save_session;
   end;
 

Parameters:

p_name - the name of the attribute

p_value - the string value to be set

p_language - the language that should be used for all value transformations

Exceptions:

VALUE_ERROR - raised if the input data does not conform to the attribute's type formatting rules.

Since:

Oracle Portal 3.0.6.6.5