1. OTIS Documentation
    1. Overview
    2. Deploying an OTIS Server
    3. Developer Documentation
      1. OTIS Functionality
      2. Samples
      3. OTIS RESTful Protocol Details
      4. Audit Logging
    4. Configuration Documentation
  2. Session Tasks
  3. Get Session Property
    1. REST
    2. Java
    3. PHP
    4. cURL
  4. Remove Session Property
    1. REST
    2. Java
    3. PHP
    4. cURL
  5. Set Session Property
    1. REST
    2. Java
    3. PHP
    4. cURL

Set Session Property

This section provides developers with information on how to set a property on a session. Documentation for the REST protocol, as well as code samples for Java, PHP, and cURL, are provided below.

REST

The REST noun (and associated message content) for setting a property on a session is as follows:

  • Relative Noun: AuthenticatedSession/$sessionID/Properties/$propertyName. This is the relative path of the URL that should appear after the OTIS server application name. The $sessionID variable identifies the authenticated session that is to be updated with a new property. The $propertyName variable identifies the property to be updated. For example: 
    https://wag.bandit-project.org/otis/AuthenticatedSession/AB6745EDF9A32BCEAB6745EDF9A32BCE/Properties/Property1
  • HTTP Method: PUT.
  • Request/Response message details: click here
  • Description: Updates a property for the authenticated session (specified by the $sessionID variable). The content of the request message (see here) contains the value the property is to be set to. NOTE: If the property does not exist, it will be created.

IMPORTANT NOTE: Session properties can also be set as part of the initial request to create an authenticated session. See here for details on how to set session properties in the authenticate request.

Java

The following is example Java code that demonstrates how to set properties on a session: 

import java.net.URI;
import java.util.Date;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.util.HashMap;

try
{

   // The following Java Object types may be set as values for properties in a session

   String   strValue = "SimpleStringValue";
   Integer  intValue = new Integer( 27);
   Boolean  boolValue = new Boolean( true);
   Long	    longValue = new Long( 5789225);
   Short    shortValue = new Short( (short)17);
   Byte	    byteValue = new Byte( (byte)12);
   byte []  byteArrayValue = {1,2,3,4,5,6};
   Double   doubleValue = new Double( 43.86);
   Float    floatValue = new Float( 582.231);
   URI      uriValue = URI.create( "https://mycorp.org/index.jsp?name=joe&phone=888-4231");
   Date     dateValue = new Date();

   // All objects inside a List object must be of the same type - in the example below they are all String objects
			
   List     strList = new ArrayList();
   strList.add( "String1");
   strList.add( "String2");
   strList.add( "String3");
   strList.add( "String4");

   // Maps may be set as property values also.  They are typically used to represent more complex properties.
   // Each item in the Map may be a different type.

   Map      complexValue = new HashMap();
   complexValue.put( "sub-boolean-value", new Boolean( false));
   complexValue.put( "sub-int-value", new Integer( 13));
   complexValue.put( "sub-string-value", "sub-string");

   // Create a Map of Maps - an even more complex property.

   Map      complexValue2 = new HashMap();
   Map      subComplexValue1 = new HashMap();
   Map      subComplexValue2 = new HashMap();
   Map      subComplexValue3 = new HashMap();
			
   subComplexValue1.put( "v1", new Boolean( false));
   subComplexValue1.put( "v2", new Integer( 45));
   subComplexValue1.put( "v3", "value3");
			
   subComplexValue2.put( "v21", new Boolean( false));
   subComplexValue2.put( "v22", new Integer( 245));
   subComplexValue2.put( "v23", "value23");
			
   subComplexValue3.put( "v31", new Boolean( false));
   subComplexValue3.put( "v32", new Integer( 345));
   subComplexValue3.put( "v33", "value33");
			
   complexValue2.put( "s1", subComplexValue1);
   complexValue2.put( "s2", subComplexValue2);
   complexValue2.put( "s3", subComplexValue3);

   // Now add the properties to the session. The session variable is an IAuthSession object.
   // These are being set BEFORE authentication so they can be used during authentication if needed.
			
   session.setProperty( "SimpleString", strValue);
   session.setProperty( "SimpleBoolean", boolValue);
   session.setProperty( "SimpleInteger", intValue);
   session.setProperty( "StringList", strList);
   session.setProperty( "ComplexValue", complexValue);

   // Now authenticate - the properties set above are available for use during authentication if needed

   session.authenticate( "urn:bandit-project:otis:authmethod:1.0:usernamePassword",
              UsernamePasswordAuthMethod.setMaterialResponse( "otistest", "otistest"));
			
   // Add some more properties AFTER authentication - this illustrates the various Java types
   // that may be set for session properties.
			
   session.setProperty( "ComplexValue2", complexValue2);
   session.setProperty( "LongValue", longValue);
   session.setProperty( "ShortValue", shortValue);
   session.setProperty( "ByteValue", byteValue);
   session.setProperty( "ByteArrayValue", byteArrayValue);
   session.setProperty( "DoubleValue", doubleValue);
   session.setProperty( "FloatValue", floatValue);
   session.setProperty( "URIValue", uriValue);
   session.setProperty( "DateValue", dateValue);
}
catch (AuthSessionException exception)
{
    System.out.println("AuthSessionException: " + exception);
}

The OTIS client Java library may be downloaded from the OTIS download page.

PHP

The following is PHP example code of how to set properties during the authentication: 

//Generate an xml for use in the body of the POST -  Note the use of the <otis:PropertyList> element to set properties during authentication.
$xml ='<?xml version="1.0" encoding="UTF-8"?>
<otis:Authenticate xmlns:otis="http://code.bandit-project.org/schemas/2008/otis"
      methodID="urn:bandit-project:otis:authmethod:1.0:usernamePassword">
   <otis:AuthMaterial materialID="urn:bandit-project:otis:authmaterial:1.0:usernamePassword" mustGatherAllChildren="true">
      <otis:AuthChildMaterials>
         <otis:AuthMaterial materialID="urn:bandit-project:otis:authmaterial:1.0:username">
            <otis:AuthMaterialValue Type="string">otisTest</otis:AuthMaterialValue>
         </otis:AuthMaterial>
         <otis:AuthMaterial materialID="urn:bandit-project:otis:authmaterial:1.0:password">
            <otis:AuthMaterialValue Type="string">otisTest</otis:AuthMaterialValue>
         </otis:AuthMaterial>
      </otis:AuthChildMaterials>
   </otis:AuthMaterial>
   <!-- Throw in some session properties that should be set on the authenticated session -->
   <otis:PropertyList>
      <otis:Property Name="SimpleString" Type="string">
         <otis:PropertyValue>SimpleStringValue</otis:PropertyValue>
      </otis:Property>
      <otis:Property Name="SimpleBoolean" Type="boolean">
         <otis:PropertyValue>true</otis:PropertyValue>
      </otis:Property>
      <otis:Property Name="SimpleInteger" Type="int">
         <otis:PropertyValue>27</otis:PropertyValue>
      </otis:Property>
      <!-- The following property is a List of strings -->
      <otis:Property Name="StringList" Type="string">
         <otis:PropertyValue>String1</otis:PropertyValue>
         <otis:PropertyValue>String2</otis:PropertyValue>
         <otis:PropertyValue>String3</otis:PropertyValue>
         <otis:PropertyValue>String4</otis:PropertyValue>
      </otis:Property>
      <!-- Complex value property -->
      <otis:Property Name="ComplexValue" Type="Map">
         <otis:PropertyValue>
            <otis:Property Name="sub-boolean-value" Type="boolean">
               <otis:PropertyValue>false</otis:PropertyValue>
            </otis:Property>
            <otis:Property Name="sub-int-value" Type="int">
               <otis:PropertyValue>13</otis:PropertyValue>
            </otis:Property>
            <otis:Property Name="sub-string-value" Type="string">
               <otis:PropertyValue>sub-string</otis:PropertyValue>
            </otis:Property>
         </otis:PropertyValue>
      </otis:Property>
   </otis:PropertyList>
</otis:Authenticate>';
$length = strlen($xml);
$Host = "wag.bandit-project.org";

// Generate the request header using an xml 
$ReqHeader =
"POST /otis/AuthenticatedSession HTTP/1.1\n".
"Host: $Host\n".
"Content-Type: application/x-www-form-urlencoded\n".
"Content-Length: $length\n".
"Connection: Close\n\n".
"$xml\n";

// Open the connection to the host
$socket = fsockopen("wag.bandit-project.org", 80);

// Do the POST; store in "Result".  "Result" can be looked at to see what the session ID is.
fputs($socket, $ReqHeader);
while (!feof($socket)) 
{
   $tmp = fgets($socket, 128);
   //if the line contains an xml tag, add it
   if(strpos($tmp, ">"))
   {
      $Result .= $tmp;
   }
}

The following example shows how to set a property AFTER a session has been authenticated (note that the $SessionURI variable would contain the authenticated session URL): 

//Generate the content to set a session property to a URI value

$strContent =
'<?xml version="1.0" encoding="UTF-8"?>' .
'<otis:Property Name="URIValue" Type="anyURI" xmlns:otis="http://code.bandit-project.org/schemas/2008/otis">' .
'   <otis:PropertyValue>https://mycorp.org/index.jsp?name=joe&phone=888-4231</otis:PropertyValue>' .
'</otis:Property>';

$length = strlen($strContent);

$putHeader = 
"PUT " . $SessionURI . " . "/Properties/URIValue HTTP/1.1\n".
"Host: $Host\n" .
(($SessionSecret) ? ("SessionSecret: " . $SessionSecret . "\n") : "") .
"Content-Type: application/x-www-form-urlencoded\n".
"Content-Length: $length\n".
"Connection: Close\n\n".
"$strContent\n";


//Set the property
echo "Set the \"URIValue\" property...\n";
$socket = fsockopen($Host, 80);
fputs($socket, $putHeader);
while(!feof($socket)) fgets($socket);
fclose($socket);

cURL

The following sample code shows how to send session properties with an authenticate request. The authentication uses a username and password. This code includes line continuations that work on Linux. 

curl -c cookies.txt -d \
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<otis:Authenticate xmlns:otis=\"http://code.bandit-project.org/schemas/2008/otis\"
                 methodID=\"urn:bandit-project:otis:authmethod:1.0:usernamePassword\">
   <otis:AuthMaterial materialID=\"urn:bandit-project:otis:authmaterial:1.0:usernamePassword\" mustGatherAllChildren=\"true\">
      <otis:AuthChildMaterials>
         <otis:AuthMaterial materialID=\"urn:bandit-project:otis:authmaterial:1.0:username\">
            <otis:AuthMaterialValue Type=\"string\">otisTest</otis:AuthMaterialValue>
         </otis:AuthMaterial>
         <otis:AuthMaterial materialID=\"urn:bandit-project:otis:authmaterial:1.0:password\">
            <otis:AuthMaterialValue Type=\"string\">otisTest</otis:AuthMaterialValue>
         </otis:AuthMaterial>
      </otis:AuthChildMaterials>
   </otis:AuthMaterial>
        <otis:PropertyList>
                <otis:Property Name=\"SimpleString\" Type=\"string\">
                        <otis:PropertyValue>SimpleString</otis:PropertyValue>
                </otis:Property>
                <otis:Property Name=\"SimpleBoolean\" Type=\"boolean\">
                        <otis:PropertyValue>true</otis:PropertyValue>
                </otis:Property>
                <otis:Property Name=\"SimpleInt\" Type=\"int\">
                        <otis:PropertyValue>27</otis:PropertyValue>
                </otis:Property>
                <otis:Property Name=\"StringList\" Type=\"string\">
                        <otis:PropertyValue>String1</otis:PropertyValue>
                        <otis:PropertyValue>String2</otis:PropertyValue>
                        <otis:PropertyValue>String3</otis:PropertyValue>
                        <otis:PropertyValue>String4</otis:PropertyValue>
                </otis:Property>
                <otis:Property Name=\"ComplexValue\" Type=\"Map\">
                        <otis:PropertyValue>
                                <otis:Property Name=\"sub-boolean-value\" Type=\"boolean\">
                                        <otis:PropertyValue>false</otis:PropertyValue>
                                </otis:Property>
                                <otis:Property Name=\"sub-int-value\" Type=\"int\">
                                        <otis:PropertyValue>13</otis:PropertyValue>
                                </otis:Property>
                                <otis:Property Name=\"sub-string-value\" Type=\"string\">
                                        <otis:PropertyValue>sub-string</otis:PropertyValue>
                                </otis:Property>
                        </otis:PropertyValue>
                </otis:Property>
        </otis:PropertyList>
</otis:Authenticate>" \
 https://wag.bandit-project.org/otis/AuthenticatedSession >authresponse.xml 2>/dev/null
sed --quiet "{s/.*:sessionSecret>\(.[0-9A-Fa-f]*\)<\/.*:sessionSecret>.*/SessionSecret: \1/p}" authresponse.xml >secret.hdr
rm authresponse.xml
Note the use of a cookies file. This will allows you to perform subsequent cURL commands without adding /AuthenticatedSession/<sessionID> to the path. Notice also how the session secret is extracted from the response and put into a file called secret.hdr. This is so that other curl scripts examples can get the session secret and send it to the OTIS server.

Expected response (note that the session identifier will be different): 

<otis:AuthenticateResponse xmlns:otis="http://code.bandit-project.org/schemas/2008/otis" >
   <otis:sessionID>74FA4E93D1720A7ACA2CD3796F471F56</otis:sessionID>
   <otis:sessionSecret>664262E5DF1768557E070AAF246D2AFA664262E5DF1768557E070AAF246D2AFA664262E5DF1768557E070AAF246D2AFA664262E5DF1768557E070AAF246D2AFA</otis:sessionSecret>
   <otis:sessionURL>https://wag.bandit-project.org/otis2/AuthenticatedSession/74FA4E93D1720A7ACA2CD3796F471F56</otis:sessionURL>
   <otis:AuthEntityID>otisTest</otis:AuthEntityID>
</otis:AuthenticateResponse>

The following sample code shows how to set a session property AFTER authentication has been done. Note the use of a cookie file to specify the session: 

if [ -e secret.hdr ] ; then secret=`cat secret.hdr` ; else secret="nosecret: none" ; fi
curl -b cookies.txt -H "${secret}" -X PUT -d \
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<otis:Property xmlns:otis=\"http://code.bandit-project.org/schemas/2008/otis\" Name=\"ComplexValue\" Type=\"Map\">
        <otis:PropertyValue>
                <otis:Property Name=\"sub-boolean-value\" Type=\"boolean\">
                        <otis:PropertyValue>true</otis:PropertyValue>
                </otis:Property>
                <otis:Property Name=\"sub-int-value\" Type=\"int\">
                        <otis:PropertyValue>26</otis:PropertyValue>
                </otis:Property>
                <otis:Property Name=\"sub-string-value\" Type=\"string\">
                        <otis:PropertyValue>sub-string-changed-value</otis:PropertyValue>
                </otis:Property>
        </otis:PropertyValue>
</otis:Property>" \
 https://wag.bandit-project.org/otis/Properties/ComplexValue/
This assumes you have already set up an authenticated session and are using a cookies.txt file to store/retrieve the otisSessionID cookie and that the session secret has been stored in a file called secret.hdr (See AuthenticateUser for details).

Expected response: none