Myna. 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

Spec Definition

• 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

• 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

• 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

Function Definition

Parameter Definition

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"]
                     }
               }
          }
     }
 }

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

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

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

Parameters

Myna.WebService.prototype.clearAuthUserId=function()

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

Parameters

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

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

Parameters

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.

if $req.data.ns is defined, this namespace is will be defined in the API

if $req.data.scriptvar is defined, a JavaScript response is generated with the Ext.Direct API set equal to the value of $req.data.scriptvar.  If $req.data.ns is also defined, then scriptvar will be created in that namespace

if $req.data.callback is defined, a JavaScript response is generated that calls callback function with the Ext.Direct API as the only parameter

Client-side Examples

// adds a Ext.Direct provider via script include with callback
<script type="text/javascript" src="myservice.ws?ext-api&callback=Ext.Direct.addProvider"></script>

// adds a 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){
        alert(response);
    })
</script>

// adds a 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){
        alert(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){
        alert(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){
        alert(response);
    })
</script>

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

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

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

Parameters

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

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

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

Parameters

Myna.WebService.prototype.executeExtRoute=function()

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