Accessing global context

Global context APIs

Values in the global context are addressed with a key reference, which has the following syntax: /<zone>/<path>[#<value_path>] .

The global context APIs are summarized with examples based on the following global context contents:

/config/foo/a = b
/config/foo/x = y
/config/map = ["a" : "b", "x" : "y"]

PHP information

Use the global context to share information between the various event handlers, which you can use WebSphere sMash to build. To enable the many language environments to access the information, there are certain restrictions on the types of information that can be placed in the global context. From the PHP perspective, objects and resources are not readily sharable, and objects in particular contain behaviors that might be dependent on the PHP runtime instance, for example, their own class definition.

Objects and resources cannot be stored in the global context. To share objects, save the values of the objects' fields by casting the object to an array.

A PHP code sample using the global context

<?php
    // Get the URI from the request.
    $uri    = zget("/request/uri");

    echo "<br/>$uri";

    // Get the user agent
    $header = zget("/request/headers/in/User-Agent");
    echo "<br/>$header";

    // List all the parameters.
    $params = zlist("/request/params",false);
    echo "<br/>The parameters<br/>";
    var_dump($params);

     // Put the status.
    zput("/request/status",200);

    // Delete a key.
    zdelete("/request/some_unwanted_key");

    // Add a header value 'no-cache'
    zpost("/request/headers/out/Cache-Control","no-cache");

    // secured pages only.
    $remoteU = zget("/request/subject#remoteUser");
    $group   = zget("/request/subject#groups");
    $roles   = zget("/request/subject#roles");
    if ($remoteU != null) {
        var_dump($remoteU);
    }
    if ($group != null) {
        var_dump($group);
    }
    if ($roles != null) {
        var_dump($roles);
    }
    echo "<br/> Page Complete";

?>

Value pathing

Value pathing is a means of referring to elements within a stored value. Specify value paths by appending fragment identifiers to the key. Details about the fragment, such as syntax and meaning, are dependent on the type handler associated with the value.

The following information summarizes the support for zput and zpost within the global context APIs:

• zput() means create, if not defined, or replace otherwise.
• zpost() means create, if not defined, or append otherwise.

Exception conditions

The global context APIs throw an IllegalArgumentException if the uri is incorrectly formed. A valid global context uri contains the following characteristics:

Maps

The Map type handler supports the #<key> fragment, and refers to the value mapped to <key>.

Lists

The List type handler supports the #<N> fragment, and refers to the N-th element in the list.

FirstElementList

FirstElementList is a variant of List that supports access to the first element as a simple object without specifying the index. FirstElementList simplifies the handling of values, such as query parameters, that are properly stored as lists, but are most commonly retrieved as single values. Within the default zones, only /request/params/<parmName> and /request/headers/in/<headerName> are instances of FirstElementList.

Because FirstElementList is used to simplify access to these particular type of lists, the most commonly used API invocations are zget("/app/someList") and zput("/app/someList", "bar"). However, the following table features the full API of FirstElementType:

Objects (default)

Nested

Value manipulation can be nested for zget() zcontains(). All other operations support up to one level of value manipulation. Parameters for value manipulation are delimited by a slash (/), as shown in the following example:

Map<String, String> innerMap0 = new HashMap<String, String>();
innerMap0.put("im0a", "a");
innerMap0.put("im0b", "b");
      
Map<String, String> innerMap1 = new HashMap<String, String>();
innerMap1.put("im1c", "c");
innerMap1.put("im1d", "d");

List<Map<String, String>> list = new ArrayList<Map<String, String>>();
list.add(innerMap0);
list.add(innerMap1);
      
Map<String, List<Map<String, String>>> map
    = new HashMap<String, List<Map<String, String>>>();
map.put("x", list);
      
zput("/config/nested", map);

      
assertEquals("b", zget("/config/nested#x/0/im0b"));
assertEquals("c", zget("/config/nested#x/1/im1c"));