The SALT
GWWS server is a configuration-driven process which, for most basic Web service applications, does not require any programming tasks. However, SALT functionality can be enhanced by developing plug-in interfaces which utilize custom typed buffer data and customized shared libraries to extend the GWWS server.
SALT supports the
P_CUSTOM_TYPE and
P_CREDENMAP plug-in ID, which is used to define plug-in interfaces for custom typed buffer data handling, and map Oracle Tuxedo user ID and group ID into username/password that HTTP Basic Authentication needs.
For the P_CUSTOM_TYPE Plug-in ID, the plug-in name is used to indicate the actual custom buffer type name. When the GWWS server attempts to convert data between Oracle Tuxedo custom typed buffers and an XML document, the plug-in name is the key element that searches for the proper plug-in interface.
For the P_CREDENMAP ID category, one function needs to be implemented:
•
|
int (* gwws_pi_map_http_basic) (char * domain, char * realm, char * t_userid, char * t_grpid, Cred_UserPass * credential);
|
Returning a 0 value indicates the function has executed successfully. Returning a value other than
0 indicates failure. If this functions fails, the plug-in is not loaded, and the GWWS server will not start.
int _ws_pi_get_Id_and_Names(int * count, char **ids, char **names);
Returning a 0 value indicates the initiating function has executed successfully. Returning a value other than
0 indicates initiation has failed. If plug-in interface initiation fails, the GWWS server will not start.
@ID@ indicates the actual plug-in ID value.
@Name@ indicates the actual plug-in name value. For example, the initiating function of a plug-in with
P_CUSTOM_TYPE as a plug-in ID and
MyType as a plug-in name
is:
_ws_pi_init_P_CUSTOM_TYPE_MyType (char * params, void **priv_ptr).
@ID@ indicates the actual plug-in ID value.
@Name@ indicates the actual plug-in name value. For example, the initiating exiting function name of a plug-in with
P_CUSTOM_TYPE as a plug-in ID and
MyType as a plug-in name is:
_ws_pi_exit_P_CUSTOM_TYPE_MyType(void * priv).
vtable is a particular C structure that stores the necessary function pointers for the actual businesss logic of a plug-in interface. In other words, a valid plug-in interface must implement all the functions defined by the corresponding vtable.
@ID@ indicates the actual plug-in ID value.
@Name@ indicates the actual plug-in name value. For example, the
vtable setting function of a plug-in with
P_CUSTOM_TYPE as a plug-in ID and
MyType as a plug-in name is:
_ws_pi_set_vtbl_P_CUSTOM_TYPE_MyType(void * priv).
The vtable structures may be different for different plug-in ID categories. For this SALT release,
P_CUSTOM_TYPE and
P_CREDENMAP are the only valid plug-in IDs.
The vtable structures for available plug-in interfaces are shown in
Listing 5‑1.
struct credmap_vtable indicates that one function must be implemented for a
P_CREDENMAP plug-in interface. For more information, see
?$paratext>?.
The function input parameter void * priv points to a concrete
vtable instance. You should set the
vtable structure with the actual functions in the
vtable setting function.
{
struct credmap_vtable * vtable;
if ( ! vtbl )
return -1;
vtable = (struct
credmap_vtable *) vtbl;
vtable->
gwws_pi_map_http_basic =
Credmap_HTTP_Basic;
return 0;
}
The function pointer (* soap_in_tuxedo__CUSTBUF), points to the customized function that converts the SOAP message payload to Oracle Tuxedo typed buffer.
The function pointer (* soap_out_tuxedo__CUSTBUF), points to the customized function that converts the Oracle Tuxedo typed buffer to SOAP message payload.
Table 5‑1 lists several message conversion plug-in use cases.
From Table 5‑1, the following message conversion plug-ins general rules are applied.
•
|
If the input and/or output (no matter if returned with TPSUCCESS or TPFAIL) buffer of an Oracle Tuxedo originated service is associated with an external XML Schema, you should develop message conversion plug-ins to handle the transformation manually (unless you are sure that the SALT default buffer type-based conversion rules can handle it correctly).
|
•
|
For example, if you associate your own XML Schema with an Oracle Tuxedo service FML32 typed buffer, you must provide a message conversion plug-in since SALT default data mapping routines may not understand the SOAP message payload structure when trying to convert into the FML typed buffer. Contrarily, the SOAP message payload structure converted from the FML typed buffer may be tremendously different from the XML shape defined via your own XML Schema.
|
The input parameter, char * xmlbuf, indicates a
NULL terminated string with the XML format data stream.
The input parameter, char * type, indicates the custom type buffer type name, this parameter is used to verify that the GWWS server expected custom typed buffer handler matches the current plug-in function.
The output parameter, CustomerBuffer *a, is used to store the allocated custom typed buffer instance. An Oracle Tuxedo custom typed buffer must be allocated by this plug-in function via the
tpalloc(). Plug-in code is not responsible to free the allocated custom typed buffer, it is automatically destroyed by the GWWS server if it is not used.
CustomerBuffer * myxml2buffer (void * xercesDOM, CustomerBuffer *a, CustType_Ext * extinfo)
{
// casting the input void * xercesDOM to class DOMDocument object
DOMDocument * DOMTree =
// allocate custom typed buffer via tpalloc
a->buf = tpalloc("MYTYPE", "MYSUBTYPE", 1024);
a->len = 1024;
// fetch data from DOMTree and set it into custom typed buffer
DOMTree ==> a->buf;
if ( error ) {
release ( DOMTree );
tpfree(a->buf);
a->buf = NULL;
a->len = 0;
return NULL;
}
release ( DOMTree );
return a;
}
"mybuffer2xml" is the function name can be specified with any valid string upon your need.
The input parameter (CustomerBuffer *a), is used to store the custom typed buffer response instance. Plug-in code is not responsible to free the allocated custom typed buffer, it is automatically destroyed by the GWWS server if it is not used.
The input parameter (char * type), indicates the custom typed buffer type name. This parameter can be used to verify if the SALT GWWS server expected custom typed buffer handler matches the current plug-in function.
The output parameter (char ** xmlbuf), is a pointer that indicates the newly converted XML payload. The XML payload buffer must be allocated by this function and uses
malloc (). Plug-in code is not responsible to free the allocated XML payload buffer, it is automatically destroyed by the GWWS server if it is not used.
If the DOMDocument is constructed from an XML string through
XercesDOMParser::parse() API. You must use
XercesDOMParser::adoptDocument() to get the pointer of the
DOMDocument object. You must not use
XercesDOMParser::getDocument() to get the pointer of the
DOMDocument object because the
DOMDocument object is maintained by the
XercesDOMParser object and is released when deleting the
XercesDOMParser object if you do not de-couple the
DOMDocument from the
XercesDOMParser via the
XercesDOMParser::getDocument() function.
Table 5‑2 compares the SALT Message Conversion Plug-in and the SALT 1.1 Custom Buffer Type Conversion Plug-in.
1.
|
Re-implement function (*soap_in_tuxedo__CUSTBUF) and (*soap_out_tuxedo__CUSTBUF) according to the SALT message conversion plug-in vtable function prototype API. The major change is that the SOAP message payload is saved as an Xerces class DOMDocument object instead of the old string value.
|
•
|
tries to invoke the vtable gwws_pi_map_http_basic function to map the Oracle Tuxedo userid into the username and password for the HTTP Realm of the server.
|
•
|
An existing Web service, myservice, sited on http://www.abc.com/webservice, requires HTTP Basic Authentication. The username is “ test”, the password is “ 1234,” and the realm is “ myrealm”.
|
•
|
Use Credmap_HTTP_Basic();
|
Set the gwws_pi_map_http_basic entry in
vtable structure
credmap_vtable with the
Credmap_HTTP_Basic() function implemented in step 1.
The "gwws_pi_map_http_basic" function name can be specified with any valid string as needed.
The input parameters, char * domain and char * realm, represent the domain name and HTTP Realm that the Web service belongs to. The plug-in code must use them to determine the scope to find appropriate credentials.
The input parameters, char * t_uid and
char * t_gid, are strings that contain Oracle Tuxedo user ID and group ID number values respectively. These two parameters may be used to find the username.
The output parameter, Cred_UserPass * credential, is a pointer that indicates a pre-allocated buffer storing the returned username/password. The plug-in code is not responsible for allocating the buffer.
int Credmap_HTTP_Basic(
char * domain, char * realm, char * t_uid, char * t_gid, Cred_UserPass * credential)
{
// Use domain and realm to determine scope
credentialList = FindAllCredentialForDomainAndRealm(domain, realm);
if ( error happens )
return -1;
// find appropriate credential in the scope
foreach cred in credentialList {
if (t_uid and t_gid match) {
*credential = cred;
return 0;
}
}
if ( not found and no default credential) {
return -1;
}
*credential = default_credential;
return 0;
}