Appendix A
HTTP/XML Interface
HTTP/XML Interface Overview
Programs or applications written in a non-Java language can also exchange information with the iPlanet Portal Server product, although non-Java-based clients are considerably less efficient to use and are more cumbersome to implement. This appendix details the processes and issues involved in communicating with the Portal Server using the exposed HTTP/XML interface (or API, of sorts).
In general, this appendix applies to writing a standalone non-Java-based application that is authenticated through the session ID from an iPlanet Portal Server session or an application that will use any of the other exposed interfaces, including Profile and Policy services, Logging, Session, or other interfaces. Non-Java applications must explicitly exchange information with the server using an over-the-wire protocol, rather than simply passing objects from class to class as a Java-based client implementation can.
The mechanism for passing information from client application to iPlanet Portal Server and back is through http post. The structure of the information to pass is defined by XML-based DTDs for each service.
Therefore, a minimal non-Java-based iPlanet Portal Server client application must implement:
HTTP 1.1 compliant client implementation to send information to the iPlanet Portal Server server
HTTP 1.1 compliant server implementation to receive information from the iPlanet Portal Server if asynchronous communication or iPlanet Portal Server -initiated communication is required
XML parser to interpret the data stream coming from the iPlanet Portal Server software
A means of producing valid XML that is compliant with a given DTD
Exchanging Information Between the Client and the Server
The conversation between client and server is as follows:
Get the property "ips.naming.url" from /etc/opt/SUNWips/platform.conf as the naming URL.
Client posts a name request to the naming URL.
Server returns name response to client.
Client parses name response to determine URLs for Session service, Profile Service, and Logging Service.
Client posts a session request to the Session Service URL.
Server returns session response to client.
Client parses session response to determine session ID to use.
Client posts a profile request to the Profile Service URL with the session ID obtained in Step 6.
Server returns profile response to client.
Client parses profile response to obtain profile attributes.
Client posts a logging request to the Logging Service URL.
Server returns logging response to client.
Client parses logging response to decide whether the logging request succeeded.
XML DTDs
The following sections outline the DTDs that define information structures for initial data exchanges between client software and the Portal Server. These exchanges negotiate the URL for the subsequent exchanges with a specific application (registered with the Profile and Policy server).
PLL Request Set DTD
The request from the Portal Server to a name response will comply with the following DTD.
Code Example A-1 PLL RequestSet DTD
<!-- This DTD is used by PLL -->
|
<!DOCTYPE RequestSet [
|
<!ELEMENT RequestSet(Request)+>
|
<!ATTLIST RequestSet
|
vers CDATA #REQUIRED
|
svcid CDATA #REQUIRED
|
reqid CDATA #REQUIRED>
|
<!ELEMENT Request(#PCDATA)*>
|
<!ATTLIST Request
|
dtdid CDATA #IMPLIED>
|
]>
|
|
PLL Response Set DTD
The response from the Portal Server to a name request will comply with the following DTD.
Code Example A-2 PLL ResponseSet DTD
<!-- This DTD is used by PLL -->
|
<!DOCTYPE ResponseSet [
|
<!ELEMENT ResponseSet(Response)+>
|
<!ATTLIST ResponseSet
|
vers CDATA #REQUIRED
|
svcid CDATA #REQUIRED
|
reqid CDATA #REQUIRED>
|
<!ELEMENT Response(#PCDATA)*>
|
<!ATTLIST Response
|
dtdid CDATA #IMPLIED>
|
]>
|
|
|
PLL Notification Set DTD
The response from the Portal Server to a notification will comply with the following DTD.
Code Example A-3 PLL NotificationSet DTD
<!-- This DTD is used by PLL -->
|
<!DOCTYPE NotificationSet [
|
<!ELEMENT NotificationSet(Notification)+>
|
<!ATTLIST NotificationSet
|
vers CDATA #REQUIRED
|
svcid CDATA #REQUIRED
|
notid CDATA #REQUIRED>
|
<!ELEMENT Notification(#PCDATA)*>
|
<!ATTLIST Notification
|
dtdid CDATA #IMPLIED>
|
]>
|
|
|
Naming Response DTD
The request from the Portal Server to a name response will comply with the following DTD.
Code Example A-4 NamingResponse DTD
<!DOCTYPE NamingResponse [
|
<!ELEMENT NamingResponse (GetNamingProfile)
|
<!ATTLIST NamingResponse
|
vers CDATA #REQUIRED
|
reqid CDATA #REQUIRED>
|
<!ELEMENT GetNamingProfile (Attribute*|Exception)>
|
<!ELEMENT Attribute EMPTY>
|
<!ATTLIST Attribute
|
name CDATA #REQUIRED
|
value CDATA #REQUIRED>
|
<!ELEMENT Exception (#PCDATA)>
|
]>
|
|
Naming Request DTD
The initial request from a client application to the Portal Server always goes to the URL:
- http://server-name:port/NamingService
- with a post, and must be XML compliant with the following DTD.
Code Example A-5 NamingRequest DTD
<!DOCTYPE NamingRequest [
|
<!ELEMENT NamingRequest (GetNamingProfile)>
|
<!ATTLIST NamingRequest
|
vers CDATA #REQUIRED
|
reqid CDATA #REQUIRED>
|
<!ELEMENT GetNamingProfile EMPTY>
|
]>
|
|
Naming Request XML
Code Example A-6 NamingRequest XML
<RequestSet vers="1.0" svcid="ips.naming" reqid="0">
|
<Request>
|
// BEGIN service specific XML message
|
<![CDATA[<NamingRequest vers="1.0" reqid="0">
|
<GetNamingProfile>
|
</GetNamingProfile>
|
</NamingRequest>]]>
|
// END service specific XML message
|
</Request>
|
</RequestSet>
|
|
Naming Response XML
Code Example A-7 NamingResponse XML
<Response>
|
|
// BEGIN service specific XML
|
<![CDATA[<NamingResponse vers="1.0" reqid="0">
|
<GetNamingProfile>
|
<Attribute name="iwtPlatform-servers"
value="huanghe.red.iplanet.com "></Attribute>
|
<Attribute name="iwtNaming-loggingClass"
value="com.iplanet.portalserver.logging.service.LogService"></At
tribute>
|
<Attribute name="iwtNaming-resourceBundle"
value="iwtNaming"></Attribute>
|
<Attribute name="iwtNaming-sessionClass"
value="com.iplanet.portalserver.session.service.SessionRequestHa
ndler"></Attribute>
|
<Attribute name="iwtNaming-profileClass"
value="com.iplanet.portalserver.profile.service.ProfileService">
</Attribute>
|
<Attribute name="iwtNaming-description"
value="Naming"></Attribute>
|
<Attribute name="iwtNaming-profileURL"
value="http://huanghe.red.iplanet.com:8080/profileservice"></Att
ribute>
|
<Attribute name="iwtNaming-loggingURL"
value="http://huanghe.red.iplanet.com:8080/loggingservice"></Att
ribute>
|
<Attribute name="iwtNaming-sessionURL"
value="http://%host:8080/sessionservice"></Attribute>
|
</GetNamingProfile></NamingResponse>]]>
|
|
// END service specific XML
|
|
</Response>
|
</ResponseSet>
|
|
Further exchanges are determined by the specific API and DTDs for the service being addressed.
Session-Related DTD and XML
Implementing the Session API functionality in non-Java languages requires providing and parsing XML-based data streams to communicate with the logging processes on the server. The following sections detail the DTDs that describe acceptable communication with the Session processes.
|
Note
|
If accessing Session API functionality through Java programs, it is not necessary to be aware of these implementation specifics, because the Java interface makes these transparent to Java programmers. See the first section of this chapter to learn to access Session API functionality through Java programs.
|
SessionNotification DTD
The Session Notification DTD establishes for structure for the server to use when providing information about the session status to a requesting client.
Code Example A-8 NotificationSet DTD
<!-- This DTD is used by PLL -->
|
<!DOCTYPE NotificationSet [
|
<!ELEMENT NotificationSet(Notification)+>
|
<!ATTLIST NotificationSet
|
vers CDATA #REQUIRED
|
svcid CDATA #REQUIRED
|
notid CDATA #REQUIRED>
|
<!ELEMENT Notification(#PCDATA)*>
|
<!ATTLIST Notification
|
dtdid CDATA #IMPLIED>
|
]>
|
|
Session Request DTD
The Session Request DTD establishes the information structure for a client application to modify or get a session from the Session server.
Code Example A-9 SessionRequest DTD
<?xml version="1.0">
|
<!DOCTYPE SessionRequest [
|
<!ELEMENT SessionRequest (GetSession |
|
GetValidSessions |
|
DestroySession |
|
Logout |
|
AddSessionListener |
|
AddSessionListenerOnAllSessions |
|
SetProperty)>
|
<!ATTLIST SessionRequest
|
vers CDATA #REQUIRED
|
reqid CDATA #REQUIRED>
|
<!ELEMENT GetSession (SessionID)>
|
<!ATTLIST GetSession
|
<!-- The reset attribute indicates whether resets the latest
access time -->
|
reset CDATA #REQUIRED>
|
<!ELEMENT GetValidSessions (SessionID)>
|
<!ELEMENT DestroySession (SessionID, DestroySessionID)>
|
<!ELEMENT Logout (SessionID)>
|
<!ELEMENT AddSessionListener (SessionID, URL)>
|
<!ELEMENT AddSessionListenerOnAllSessions (SessionID, URL)>
|
<!ELEMENT SetProperty (SessionID, Property)>
|
<!ELEMENT Property>
|
<!ATTLIST Property
|
name CDATA #REQUIRED
|
value CDATA #REQUIRED>
|
<!ELEMENT SessionID (#PCDATA)>
|
<!ELEMENT DestroySessionID (#PCDATA)>
|
<!ELEMENT URL (#PCDATA)>
|
]>
|
|
|
Session Response DTD
The Session Response DTD defines the information structure for the server's response to a session request.
Code Example A-10 SessionResponse DTD
<?xml version="1.0">
|
<!DOCTYPE SessionResponse [
|
<!ELEMENT SessionResponse(GetSession |
|
GetActiveSessions |
|
DestroySession |
|
Logout |
|
AddSessionListener |
|
AddSessionListenerOnAllSessions |
|
SetProperty)>
|
<!ATTLIST SessionResponse
|
vers CDATA #REQUIRED
|
reqid CDATA #REQUIRED>
|
<!ELEMENT GetSession (Session|Exception)>
|
<!ELEMENT GetActiveSessions (SessionList|Exception)>
|
<!ELEMENT DestroySession (OK|Exception)>
|
<!ELEMENT Logout (OK|Exception)>
|
<!ELEMENT AddSessionListener (OK|Exception)>
|
<!ELEMENT AddSessionListenerOnAllSessions (OK|Exception)>
|
<!ELEMENT SetProperty (OK|Exception)>
|
<!ELEMENT Session (Property)*>
|
|
<!ATTLIST Session
|
sid CDATA #REQUIRED
|
stype (user|application) "user"
|
cid CDATA #REQUIRED
|
cdomain CDATA #REQUIRED
|
maxtime CDATA #REQUIRED
|
maxidle CDATA #REQUIRED
|
maxcaching CDATA #REQUIRED
|
timeleft CDATA #REQUIRED
|
timeidle CDATA #REQUIRED
|
state (invalid|valid|inactive|destroyed) "invalid">
|
<!ELEMENT Property>
|
<!ATTLIST Property
|
name CDATA #REQUIRED
|
value CDATA #REQUIRED>
|
<!ELEMENT SessionList (Session)*>
|
<!ELEMENT OK (#PCDATA)>
|
<!ELEMENT Exception (#PCDATA)>
|
]>
|
|
|
Session Request XML
Code Example A-11 SessionRequest XML
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
|
<RequestSet vers="1.0" svcid="session" reqid="2">
|
<Request>
|
<![CDATA[<SessionRequest vers="1.0" reqid="1">
|
<GetSession reset="true">
|
<SessionID>fbaaa321f508529d@huanghe.eng.sun.com</SessionID>
|
</GetSession>
|
</SessionRequest>]]>
|
</Request>
|
</RequestSet>
|
|
Session Response XML
Code Example A-12 SessionResponse XML
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
|
<ResponseSet vers="1.0" svcid="session" reqid="2">
|
<Response>
|
<![CDATA[<SessionResponse vers="1.0" reqid="1">
|
<GetSession>
|
<Session sid="fbaaa321f508529d@huanghe.eng.sun.com" stype="application"
|
cid="authentication" cdomain="sun.com" maxtime="153722867280912930"
|
maxidle="153722867280912930" maxcaching="153722867280912930"
|
timeidle="0" timeleft="153722867280912930" state="valid">
|
</Session></GetSession>
|
</SessionResponse>]]>
|
</Response>
|
</ResponseSet>
|
|
Profile and Policy-related DTD and XML
Implementing the Profile and Policy API functionality in non-Java languages requires providing and parsing XML-based data streams to communicate with the Profile and Policy processes on the server.
|
Note
|
If accessing Profile and Policy API functionality through Java programs, you need not be aware of these implementation specifics, because the Java interface makes these transparent to Java programmers. See the first section of this chapter to learn to access Profile and Policy API functionality through Java programs.
|
The following sections provide the DTDs that describe XML formats used for communicating with the Profile and Policy Service processes on the server. Non-Java programs must implement XML parsers to send requests to the server logging process in these formats as well as to interpret the XML-based responses from the server Profile and Policy process.
.
Code Example A-13 ProfileService DTD
<!ELEMENT ProfileService
(Message|GetProfile|SetProfile|DelProfile|
|
GetChildRoles|SetParent|
GetParent|GetUsers|Profile|Priv|Att|
|
Exception|Data*|AddProfileListner|RemoveProfileListener|Notifica
tion)>
|
<!ATTLIST ProfileService
|
reqid CDATA #REQUIRED
|
ver CDATA #REQUIRED>
|
|
<!ELEMENT Message (#PCDATA)*>
|
<!ELEMENT Profile (Att*,Priv*)>
|
<!ATTLIST Profile
|
profileName CDATA #REQUIRED
|
profileType CDATA #REQUIRED>
|
|
<!ELEMENT Att
(Value*,Choice*,(ReadPermission?)*,(WritePermission?)*)>
|
<!ATTLIST Att
|
attName CDATA #REQUIRED
|
attId CDATA
|
attMessage CDATA
|
attType (string | number | boolean | singlechoice |
multichoice
|
|protected | stringlist | numberlist ) "string"
|
remoteFlag (true|false) "false"
|
overrideFlag (true|false) "true"
|
inheritFlag (true|false) "false">
|
<!ELEMENT Value (#PCDATA)>
|
<!ELEMENT ReadPermission (#PCDATA)>
|
<!ELEMENT WritePermission (#PCDATA)>
|
|
<!ELEMENT Priv (Allow*,Deny*)>
|
<!ATTLIST Priv
|
privName CDATA #REQUIRED
|
privId CDATA
|
privMessage CDATA
|
privType (boolean | list) #REQUIRED>
|
<!ELEMENT Allow (#PCDATA)>
|
<!ELEMENT Deny (#PCDATA)>
|
|
<!ELEMENT Exception (#PCDATA)>
|
|
<!ELEMENT Data (#PCDATA)>
|
|
<!ELEMENT GetProfile (Profile)>
|
<!ATTLIST GetProfile
|
admin (true|false) "false" #REQUIRED>
|
|
<!ELEMENT SetProfile (Profile)>
|
|
<!ELEMENT DelProfile (Profile)>
|
|
<!ELEMENT GetChildRoles (Wildchar?)>
|
<!ATTLIST GetChildRoles
|
parent CDATA #REQUIRED>
|
|
<!ELEMENT GetParent EMPTY >
|
<!ATTLIST GetParent
|
child CDATA #REQUIRED>
|
|
<!ELEMENT SetParent (#PCDATA)>
|
<!ATTLIST SetParent
|
child CDATA #REQUIRED>
|
|
<!ELEMENT GetUsers (wildchar?)>
|
<!ATTLIST GetUsers
|
parent CDATA #REQUIRED>
|
|
<!ELEMENT AddProfileListner Empty>
|
<!ATTLIST AddProfileListner
|
profileName CDATA #REQUIRED
|
listnerURL CDATA #REQUIRED>
|
|
<!ELEMENT RemoveProfileListner Empty>
|
<!ATTLIST RemoveProfileListner
|
profileName CDATA #REQUIRED
|
listnerURL CDATA #REQUIRED>
|
|
<!ELEMENT Wildchar (#PCDATA)>
|
<!ELEMENT Role (#PCDATA)>
|
|
|
Getting an Attribute Value Using XML
Code Example A-14 GetProfile Request XML
Profile request: get iwtPlatform-locale value
|
|
<ProfileService ver="1.0" reqid="0"><GetProfile
searchFlag="false" admin="false"><Profile
profileName+"/component/iwtPlatform" profileType="7"><Att
attName="iwtPlatform-locale"></Att></Profile><?GetProfile></Prof
ileService>
|
|
Code Example A-15 GetProfile Response XML
Profile request: get iwtPlatform-locale value
|
|
<ProfileService ver="1.0" reqid="0"><Profile><Att
attName+"iwtPlatform-locale" attType="string" attId=""
attDes="Platform Locale" inheritFlag="true" overrideFlag="false"
remoteFlag="false"
emptyFlag="false"><Value>en_US</Value><ReadPermission>ADMIN</Rea
dPermission>OWNER</ReadPermission><WritePermission>ADMIN</WriteP
ermission></Att></Profile></ProfileService>
|
|
Log-related DTDs
Implementing the Log API functionality in non-Java languages requires providing and parsing XML-based data streams to communicate with the logging processes on the server.
|
Note
|
If accessing Log API functionality through Java programs, you need not be aware of these implementation specifics, because the Java interface makes these transparent to Java programmers. See the first section of this chapter to learn to access Log API functionality through Java programs.
|
The following sections detail the DTDs that describe acceptable communication with the logging processes.
DTD for Log API Communication
Code Example A-16 DTD for Log API Communication
<?XML version="1.0">
|
<!--This DTD is used by Logging operation-->
|
<!DOCTYPE logging[
|
|
<!ELEMENT logCreate (log)>
|
<!ELEMENT logDelete (log)>
|
<!ELEMENT logRecWrite (log, logRecord*)>
|
<!ELEMENT logRecRead (log, queryString?)>
|
<!ELEMENT logList (log*)>
|
|
<!ELEMENT log>
|
<!ATTLIST log
|
logName CDATA #REQUIRED
|
status CDATA #IMPLIED
|
maxFileSize CDATA #IMPLIED
|
numHistoryFile CDATA #IMPLIED
|
location CDATA #IMPLIED
|
>
|
|
<!ELEMENT queryString (#PCDATA)>
|
|
<!ELEMENT logRecord (recType, recMsg)>
|
<!ELEMENT recType (#PCDATA)>
|
<!ELEMENT recMsg (#PCDATA)>
|
|
]
|
|