Programming Guides › Programming Guide for Java › Utilities Package

Utilities Package

This section contains the following topics:

Purpose of the Utilities Package

Classes for Internal Use

Connection Class

Session Class

Result Class

Exception Class

Property Class

Purpose of the Utilities Package

If you plan to call functions in the Policy Management API or the DMS API, you must use the functions in the Utilities package to build your Java application.

The SmApiConnection, SmApiResult, SmApiSession, SmApiException, and SmProperty classes in the Utilities package provide services such as:

• Establishing a connection to the Policy Server
• Obtaining a session
• Providing a result object that stores results of API requests
• Handling exceptions and results
• Encapsulating property data

Classes for Internal Use

The Utilities package provides these classes for SiteMinder internal use only:

• SmApiConstants
• SmApiObject
• SmApiPropertySets
• SmApiExportFileHandler
• SmApiImportFileHandler
• SmFlag

These classes are used internally to define methods in the Policy Management API and the DMS API.

Connection Class

Use the SmApiConnection class to create an API connection object and establish a connection between the Agent API and Policy Server. Depending upon the constructor you use, you can establish either a default connection or a user-defined connection.

The core methods of the SmApiConnection class are as follows:

Note: Do not call the execute() method from your client application. This method is for internal use only.

Session Class

The Session class, SmApiSession, lets you create a session object by passing in a valid API connection and, depending upon the constructor you use, a session specification. (A session specification is also known as a session ticket).

The core methods of the SmApiSession class are as follows:

Note: For login and logout of end users, DMS organization administrators, and DMS super administrators, use the AgentAPI.login() and AgentAPI.logout() methods in the Agent API package.

Result Class

The Result class, SmApiResult, stores the result of a SiteMinder Java API request. A SiteMinder result contains the following elements:

• Facility. Origin of the result. For example, the result might originate on the client or server.
• Severity. Significance of the result, such as informational or warning.
• Status. Status code of the result. Status codes are unique within each facility. You can use a facility’s unique status code to distinguish a particular result from other results that might have originated from the facility.
• Message. Additional information about the result, such as descriptive text or numeric details.

A result might also include a reason code. For example, a password policy result might include a reason code of 1001, meaning that the password does not contain the required minimum number of characters. To find a reason code for a result, call getReason().

All server-side errors are returned as results, not as exceptions. However, when a client-side exception is thrown, an SmApiResult object is embedded in the exception.

Interpret a Result Object

Each result object and its Facility/Severity/Status combination are represented by a unique value. These unique values are associated with predefined constants defined in the SmApiResult class—for example, SERVER_CONFIGURATION_FAILURE.

To determine the Facility/Severity/Status information for a result, you can call the equals() method to compare the returned SmApiResult object with the result constants.

• Facility: FACILITY_CONNECTION
• Severity: SEVERITY_ERROR
• Status: 4
• Message: Unable to get server configuration

You can output a result object as a string—for example, you can generate a result string by calling toString() on the SmApiResult object.

A result string has five space-separated name/value pairs in the following format:

[facility=facility severity=severity reason=reason
status=statusCode message=message]

For example, suppose you call toString() for an SmApiResult object that occurs because a user attempted to create a password with fewer than the minimum number of alphabetic characters. The method might return a result string that looks like this:

[facility=4 severity=3 reason=1008 status=13 message=nArg=1,Arg1=3]

The fields in the result have the following meanings:

• facility=4. The result originated on the server.
• severity=3. The result is an error.
• reason=1008. The error occurred because the requested password has fewer than the minimum number of alphabetic characters required for passwords.
• status=13. The unique result status code for this facility.
• message=nArg=1,Arg1=3. An additional description of the result. The two parts to this field have the following meanings:
  • nArg1=1. The error contains just one error description.
  • Arg1=3. The error description is 3. In the context of reason code 1008, the Arg1 value means that a password is required to have a minimum of 3 alphabetic characters.

Core Methods in the Result Class

The core methods of the SmApiResult class include:

Exception Class

The Exception class, SmApiException, contains the result class SmApiResult. The following packages use SmApiException:

• com.netegrity.sdk.policyapi
• com.netegrity.sdk.dmsapi
• com.netegrity.sdk.apiutil

  The core methods of the SmApiException class include:
  

The Exception class extends java.lang.Exception. By calling the inherited getMessage() method, you can retrieve the message associated with the exception.

Property Class

The Property class, SmProperty, holds the following information about a property:

• Name
• Value
• Type (encrypted / plain)

  The core methods of the SmProperty class include: