Overview | Package | Object Type | Deprecated | Index | Help
| Oracle9iAS Portal PL/SQL API Reference - 9.0.2.6
PREV TYPE NEXT TYPE | FRAMES NO FRAMES
SUMMARY: ATTRIBUTE | CONSTRUCTOR | FUNCTION/PROCEDURE | DETAIL: ATTRIBUTE | CONSTRUCTOR | FUNCTION/PROCEDURE

## 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

Attribute Summary
`_domain` | `varchar2(30)`
`_element_data` | `wwsto_session_elements`
`_id` | `integer`
`_session_id` | `integer`
`_sub_domain` | `varchar2(200)`

Function/Procedure Summary
`static drop_session` Removes the content of a session store object. | ``
`member dump_session` Dumps the content of a session store object to an output buffer. | ``
`member get_attribute_as_date` Returns the value of a date attribute. | `date`
`member get_attribute_as_number` Returns the value of a numeric attribute. | `number`
`member get_attribute_as_string` Returns the value of a string attribute. | `varchar2`
`member get_attribute_as_varchar2` Returns the value of a varchar2 attribute. | `varchar2`
`member get_attribute_index` Get the index of a particular attribute in the internal storage structure. | `integer`
`member get_domain` Returns the domain of a session store object. | `varchar2`
`member get_sub_domain` Returns the subdomain of a session store object. | `varchar2`
`member is_empty` Is this session store object empty? See load_session for when an empty session store object is created. | `boolean`
`static load_session` Loads and then returns a copy of a session store object. | `wwsto_api_session`
`member save_session` Saves session data. | ``
`member set_attribute` Sets the date value of an attribute. | ``
`member set_attribute` Sets the numeric value of an attribute. | ``
`member set_attribute` Sets the varchar2 value of an attribute. | ``
`member set_attribute_as_string` Call this procedure to set the value of the attribute given a type-specific, NLS formatted string. | ``

Attribute Detail

### _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)

Function/Procedure Detail

### 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

Overview | Package | Object Type | Deprecated | Index | Help
| Oracle9iAS Portal PL/SQL API Reference - 9.0.2.6
PREV TYPE NEXT TYPE | FRAMES NO FRAMES
SUMMARY: ATTRIBUTE | CONSTRUCTOR | FUNCTION/PROCEDURE | DETAIL: ATTRIBUTE | CONSTRUCTOR | FUNCTION/PROCEDURE