Myna. WebService

A WebService meta object that can serve requests for SOAP, XML-RPC, JSON-RPC, JSON-MYNA, and Ext.Direct

Detail

This object can be used directly to implement web rpc services or as a wrapper around existing objects.  For SOAP, this attempts to provide the simplest usable implementation.  For the simpler XML-RPC JSON-RPC, and Ext.Direct specifications, this object aims to provide a complete implementation.

JSON-MYNA

This is a Myna specific protocol that aims to be the simplest implementation of WebService.  Requests are made via GET or POST.  A parameter “method” must be passed to indicate which function on this WebService to execute.  All other GET or POST parameters are assumed to be named function parameters.  The response body will be a JSON encoding of the function result without any extra metadata.

See

  • WebService for how to construct a web service
  • handleRequest for how to call the web service using each of the supported protocols

See Also

Summary
Myna. WebServiceA WebService meta object that can serve requests for SOAP, XML-RPC, JSON-RPC, JSON-MYNA, and Ext.Direct
Functions
WebServiceConstructor function for WebService class
generateQueryTypeStatic function that takes a columns definition and returns a type that represents the Myna.Query.result type for the supplied columns that is suitible for use in the “returns” section of a web service function definition
handleRequestParses a request and returns the appropriate data;
getAuthUserAttempts to find and return the Myna.Permissions.User record for the user indicated in <WebService.authUserId>
setAuthUserIdsets <WebService.authUserId> and calls $cookie.setAuthUserId
clearAuthUserIdsets WebService.authUserId to null and calls $cookie.clearAuthUserId
executeFunctionHandlerINTERNAL handles the execution of web service function.
printHelpprints an HTML response to the requester with documentation of this WebService
printWsdlprints a SOAP WSDL document representing this web service
printExtApiprints a JSON Ext.Direct API representing this web service.
executeJsonRpcPostparses the supplied JSON-RPC request data, executes that requested funtion, and prints a JSON-RPC response text
executeJsonMynaparses the supplied JSON-MYNA request data, executes that requested funtion, and prints a JSON response text
executeXmlRpcparses the supplied XML-RPC request xml, executes that requested funtion, and prints a XML-RPC response text
executeSoapparses the supplied SOAP request XML, executes that requested funtion, and prints a SOAP response envelope
executeExtRouteparses the supplied EXT-ROUTE requests, executes that requested functions, and prints the appropriate response

Functions

WebService

Myna.WebService = function(spec)

Constructor function for WebService class

Detail

Web services are defined by creating a file with a “.ws” extension containing an object literal as defined in “Spec Definition” below.  This file will be handled internally like this:

new Myna.WebService(<.ws file contents>).handleRequest($req)

Parameters

specobject that describes a web service, or a MynaPath to a file that contains the WebService spec, or a Myna.File object that points to a file that contains the WebService spec.  See below for spec object definition

Spec Definition

nameA name for this set of services.  Like a class name
descA string describing this service set
authFunctionOptional default null Function that handles authentication before each function request.  This function will be called with a single parameter, an object with these properties:
  • username - supplied username
  • password - supplied password
  • user - Myna.Permissions.User object associated with this cookie.  To associate a user with this call $cookie.setAuthUserId
  • functionName - name of function called
  • functionDef - reference to the function definition called Returning false from this function will request an HTTP basic auth request.  Returning true will allow the request to continue.  Throwing an exception will return an error to the client.  The “this” scope is this WeService instance
beforeHandlerOptional default null A function to execute after authFunction but before processing the function handler.  This function is called with three parameters:
  • name - the name of the function handler
  • def - a reference to the function definition
  • params - an object of the function parameters to request.  The “this” scope is this WeService instance
afterHandlerOptional default null A function to execute after processing the function handler.  This function is called with four parameters:
  • name - the name of the function handler
  • def - a reference to the function definition
  • params - an object of the function parameters to request.
  • retval - the return value from the request The “this” scope is this WeService instance
functionsAn object where each property is a function name and the value is an object representing a function definition as described below

Function Definition

descOptional default null A string describing this function
paramsAn array of Parameter Definitions.  See below
handlerFunction to execute.
scopeOptional default: WebService instance Object to use as “this” when executing the handler.
returnsA representation of the type of data to return.  If this is a string, it should be one of these type names: “string,numeric,date,date_time”.  If this is an array object, then the first item should be either a string type name, another array, or an object.  If this is an object, each property should be set equal to either a string type name, another object, or an array.

Parameter Definition

namename of the parameter
typeType of the parameter.  Currently, the only available types are “string,numeric,date,date_time”
descOptional default null description of the parameter Returns: A reference to WebService instance

Example

//MyService.ws
{
name:"MyService",
desc:"A thing that does stuff",
myFunction:function(arg1,arg2){
// arbitrary functions and properties can be defined on the spec object.
// in this case "myFunction" can be accessed as "this.myFunction" in
// authFunction, beforeHandler, afterHandler or in the handler function
// requested

},
authFunction:function(authData){
// authData contans:
// * username - supplied username
// * password - supplied password
// * user - <Myna.Permissions.User> object
// associated with this cookie. To
// associate a user with this call
// <$cookie.setAuthUserId>
// * functionName - name of function called
// * functionDef - reference to the function
// definition called
// returning true allows the cal, and false requests a login. Generally
// you want to return false if the username or password is invalid, and
// throw an exception if

return true;
},
beforeHandler:function(name,def,params){
// name - the name of the function handler
// def - a reference to the function definition
// params - an object of the function parameters torequest.
//
// This is called after authFunction but before the handler function.
// This function can manipulate the "params" object before the handler is
// called, or can throw an error to abort processing
},
afterHandler:function(name,def,params,result){
// name - the name of the function handler
// def - a reference to the function definition
// params - an object of the function parameters to the request.
// result - result of the handler call
//
// This is called after the handler function but before out processing.
// This is generally used for logging, or manipulating the result
},
functions:{
echo:{
desc:"returns your parameters as an html table",
returns:"string",
params:[{
name:"arg_string",
type:"string",
desc:"A string params"
},{
name:"arg_number",
type:"numeric",
desc:"A numeric param"
},{
name:"arg_date",
type:"date",
desc:"A date param"
}],
handler:function(params){
return Myna.dump(params)
}
},
get_spec:{
desc:"returns the spec object as JSON string",
returns:"string",
params:[],
handler:function(){
//you can access the spec as "this"
return this.toJson()
}
},
get_bob:{
desc:"Always returns bob. Example of a complex return type",
returns:{
name:"string",
age:"numeric",
children:[{
name:"string",
age:"numeric"
}],
favorite_colors:["string"]
},
params:[],
handler:function(){
return {
name:"Bob Dobb",
age:"44",
children:[{
name:"julie",
age:9
},{
name:"sam",
age:13
}],
favorite_colors:["yellow","green","blue"]
}
}
}
}
}

generateQueryType

Myna.WebService.generateQueryType=function(columns)

Static function that takes a columns definition and returns a type that represents the Myna.Query.result type for the supplied columns that is suitible for use in the “returns” section of a web service function definition

Parameters

columnsAn array of objects in the form of [{colname:type}] that represents the columns in the returned query.  “Type” should be one of string, numeric, date, date_time

handleRequest

Myna.WebService.prototype.handleRequest=function()

Parses a request and returns the appropriate data;

Detail

This function examines $req.data for possible rpc calls.

  • SOAP If $req.data.wsdl is defined, a SOAP WSDL document is printed.
  • SOAP If $req.data.soap is defined, the XML content is interpreted as a SOAP request and a SOAP envelope is printed
  • XML-RPC If $req.data.xml-rpc is defined, the XML content is interpreted as an XML-RPC request and an XML-RPC response is printed
  • JSON-RPC If $req.data.json-rpc is defined, the text content is interpreted a JSON-RPC request and an JSON-RPC response is printed
  • JSON-MYNA If $req.data.json-myna is defined, the text content is interpreted a JSON-MYNA request and a plain JSON response is printed
  • Ext.Direct If $req.data.ext-api is defined a JSON Ext.Direct api is generated.  If $req.data.scriptvar is also defined, a javascript response is generated with thet Ext.Direct api set equal to the value of $req.data.scriptvar.  This allows the loading of the api via a script table like this:
//creates a global MyServiceAPI variable containing the Ext.Direct API
<script src="http://myhost.com/myservice.ws?ext-api&scriptvar=MyServiceAPI"></script>
  • Ext.direct If $req.data.ext-route is defined, the request is handled as either an Ext.Direct batch request or as an Ext.Direct POST request

getAuthUser

Myna.WebService.prototype.getAuthUser=function()

Attempts to find and return the Myna.Permissions.User record for the user indicated in <WebService.authUserId>

setAuthUserId

Myna.WebService.prototype.setAuthUserId=function(user_id)

sets <WebService.authUserId> and calls $cookie.setAuthUserId

Parameters

user_iduser_id of user to register

clearAuthUserId

Myna.WebService.prototype.clearAuthUserId=function()

sets WebService.authUserId to null and calls $cookie.clearAuthUserId

Parameters

user_iduser_id of user to register

executeFunctionHandler

Myna.WebService.prototype.executeFunctionHandler=function(functionName,
functionDef,
paramArray)

INTERNAL handles the execution of web service function.  Used by service specific function handlers

Parameters

functionNamename of method being executed
functionDefreference to the function definition in the spec
paramArrayarray of parameters to the method

printHelp

Myna.WebService.prototype.printHelp=function()

prints an HTML response to the requester with documentation of this WebService

printWsdl

Myna.WebService.prototype.printWsdl=function()

prints a SOAP WSDL document representing this web service

printExtApi

Myna.WebService.prototype.printExtApi=function(req)

prints a JSON Ext.Direct API representing this web service.

By default, this function returns a JSON Ext.Direxct API.  Additional URL parameters may be added to return a JavaScript response and/or change the namespace and actino names in the returned API

URL Parameters

nsIf supplied, this will set the “ns” property of the API which will result in the this action being loaded into that object in the browser
scriptvarIf supplied, a JavaScript response is generated with the Ext.Direct API set equal to the value of scriptvar.  If ns is also defined, then scriptvar will be created in that namespace
callbackIf supplied, a JavaScript response is generated with the Ext.Direct API passed as a parameter to a function named callback.  Typically “Ext.Direct.addProvider” is used for this but you can declare your own function if you want to manipulate the API client-side before registering.
actionBy default, the value of action property of the generated API is set to the name of this WebService.  If action is passed, then that value is used instead.  This sets the name of the resulting API object in the browser

Note

The generated Ext.Direct API contains 2 methods for every function.  The methods that start with “$” always accept 1 parameter that contains a JS object where each property is a param to the service function.  The “$” version is required when using optional parameters.  Almost all instances of “directFn” in Ext components, such as grids and combos, require this form.

//using this WebService API :
...
qry_content:{
desc:<ejs>
Queries all content blocks, 25 rows at a time, optionally
filtering by a search string
</ejs>,
params:[
{ name:"start", type:"numeric", defaultValue:0 },
{ name:"limit", type:"numeric", defaultValue:25 },
{ name:"sort", type:"string", defaultValue:'title' },
{ name:"dir", type:"string", defaultValue:'asc' },
{ name:"search", type:"string", defaultValue:"" }
],
...

//traditional, each param must be defined
MyService.qry_content(0, 25, "title","asc","CES",function(response){
debug_window(response);
})

//"$" version allows the passing of only the significant properties
MyService.$qry_content({search:"CES"},function(response){
debug_window(response);
})

API import Examples

Adding an Ext.Direct provider via script include with callback:

<script
type="text/javascript"
src="myservice.ws?ext-api&callback=Ext.Direct.addProvider"
></script>

<script>
MyService.myFunction(function(result){
debug_window(result)
})
</script>

Adding an Ext.Direct provider via script include with callback namespace and action:

<script
type="text/javascript"
src="myservice.ws?ext-api&callback=Ext.Direct.addProvider&ns=C&action=direct"
></script>

<script>
C.direct.myFunction(function(result){
debug_window(result)
})
</script>

Adding an Ext.Direct provider via AJAX callback

<script>
Ext.Ajax.request({
url:"http://myhost.com/myservice.ws?ext-api",
success:function(response){
Ext.Direct.addProvider(Ext.decode(response.responseText));
}
})
MyService.someFunction(arg1, arg1,function(response){
debug_window(response);
})
</script>

Adding an Ext.Direct provider in the MyNS namespace via AJAX callback

<script>
Ext.Ajax.request({
url:"http://myhost.com/myservice.ws?ext-api",
success:function(response){
Ext.Direct.addProvider(Ext.decode(response.responseText));
}
})
MyService.someFunction(arg1, arg1,function(response){
debug_window(response);
})
</script>

Creates a global MyServiceAPI variable containing the Ext.Direct API via script include:

//

<script src="http://myhost.com/myservice.ws?ext-api&scriptvar=MyServiceAPI"></script>
<script>
Ext.Direct.addProvider(MyServiceAPI);
MyService.someFunction(arg1, arg1,function(response){
debug_window(response);
})
</script>

Creates a MyServiceAPI variable in the MyNS namespace containing the Ext.Direct API via script include:

//

<script src="http://myhost.com/myservice.ws?ext-api&ns=MyNS&scriptvar=MyServiceAPI"></script>
<script>
Ext.Direct.addProvider(MyNS.MyServiceAPI);
MyNS.MyService.someFunction(arg1, arg1,function(response){
debug_window(response);
})
</script>

executeJsonRpcPost

Myna.WebService.prototype.executeJsonRpcPost=function(dataString)

parses the supplied JSON-RPC request data, executes that requested funtion, and prints a JSON-RPC response text

Parameters

dataStringString object containing the JSON-RPC request

executeJsonMyna

Myna.WebService.prototype.executeJsonMyna=function(data)

parses the supplied JSON-MYNA request data, executes that requested funtion, and prints a JSON response text

Parameters

dataStringString object containing the JSON-RPC request

executeXmlRpc

Myna.WebService.prototype.executeXmlRpc=function(xml)

parses the supplied XML-RPC request xml, executes that requested funtion, and prints a XML-RPC response text

Parameters

xmlXML object containing the XML-RPC request

executeSoap

Myna.WebService.prototype.executeSoap=function(xml)

parses the supplied SOAP request XML, executes that requested funtion, and prints a SOAP response envelope

Parameters

xmlXML object containing the SOAP request

executeExtRoute

Myna.WebService.prototype.executeExtRoute=function()

parses the supplied EXT-ROUTE requests, executes that requested functions, and prints the appropriate response

Myna.WebService = function(spec)
Constructor function for WebService class
Myna.WebService.generateQueryType=function(columns)
Static function that takes a columns definition and returns a type that represents the Myna.Query.result type for the supplied columns that is suitible for use in the “returns” section of a web service function definition
contains just data result of this query.
Myna.WebService.prototype.handleRequest=function()
Parses a request and returns the appropriate data;
Myna.WebService.prototype.getAuthUser=function()
Attempts to find and return the Myna.Permissions.User record for the user indicated in WebService.authUserId
Myna.WebService.prototype.setAuthUserId=function(user_id)
sets WebService.authUserId and calls $cookie.setAuthUserId
setAuthUserId:function(user_id,
cookieOptions)
sets a cookie that contains the supplied user_id and a timestamp
Myna.WebService.prototype.clearAuthUserId=function()
sets WebService.authUserId to null and calls $cookie.clearAuthUserId
clearAuthUserId:function()
Clears the “myna_auth_cookie”.
Myna.WebService.prototype.executeFunctionHandler=function(functionName,
functionDef,
paramArray)
INTERNAL handles the execution of web service function.
Myna.WebService.prototype.printHelp=function()
prints an HTML response to the requester with documentation of this WebService
Myna.WebService.prototype.printWsdl=function()
prints a SOAP WSDL document representing this web service
Myna.WebService.prototype.printExtApi=function(req)
prints a JSON Ext.Direct API representing this web service.
Myna.WebService.prototype.executeJsonRpcPost=function(dataString)
parses the supplied JSON-RPC request data, executes that requested funtion, and prints a JSON-RPC response text
Myna.WebService.prototype.executeJsonMyna=function(data)
parses the supplied JSON-MYNA request data, executes that requested funtion, and prints a JSON response text
Myna.WebService.prototype.executeXmlRpc=function(xml)
parses the supplied XML-RPC request xml, executes that requested funtion, and prints a XML-RPC response text
Myna.WebService.prototype.executeSoap=function(xml)
parses the supplied SOAP request XML, executes that requested funtion, and prints a SOAP response envelope
Myna.WebService.prototype.executeExtRoute=function()
parses the supplied EXT-ROUTE requests, executes that requested functions, and prints the appropriate response
A Javascript friendly proxy for java.io.File
Provides access to user specific permissions.