Universal Remoting Service Browser API

The service browser works in conjunction with a remote service names org.osflash.ur.ServiceBrowser. In order for the class to be as self-contained as possible, the remote service will only send untyped objects and arrays.

ServiceBrowser has the following methods:

• Description: returns the capabilities of the ServiceBrowser as currently implemented. Universal Remoting enabled projects may choose to implement all or some of the capabilities of the front-end.
• Arguments: none
• Returns: an array of objects. Each object should be in the format {name:String, version:Number, data:*}.

Proposed capabilities (currently all have data set to null):

• authentication: This Remoting implementation supports AMF0/AMF3 authentication
• secure: The user of the service browser must authenticate him/herself with the unlock method before accessing it. The roles of all the methods except verifyLogin and getCapabilities should be set to admin.
• codegen: This service browser supports code generation
• codesave: This service browser supports code saving. data in this case may contain the enabled key. If enabled is set to false, indicates that the remote class has the remote code saving capability, but it is disabled because of a lack of permissions in the target directory. if data is null, assume enabled is true.

Evert: would like to see namespaces capabilites, e.g. org.osflash.ur.authentication, org.osflash.ur.codegen

Patrick: makes sense

• Description: dummy function to verify that login is correct
• Roles: admin
• Arguments: none
• Returns: true if the password is right, error event if not

Evert: is this really needed? We can throw exceptions in AMF0 if a user doesn’t have the permission, where the servicebrowser can respond to.. also in AMF3 we can respond immediately to a Login CommandMessage..

Patrick: In AMF0 a generic /onStatus message will be generated, but the codes for missing authentication are not the same across Remoting implementations, so we can’t reliably determine whether we have an authentication error or a generic error

• Description: returns a list of remote services that are available
• Arguments: none
• Returns: an object in the following style:

{services:
 {
  "com.packageName":
  [
   "Clazz1", 
   "Clazz2",
   "Clazz3"
  ]
  "topLevel":
  [
   "Clazz1",
   "Clazz2"
  ]
 }
}

Evert: could we get a an array of objects here.. in the case people want to build on top of the api?

Patrick: I guess it’s not impossible that classes within the same package might be of different types. How about:

"topLevel":
[
 {name:"Clazz1",type:"service",data:null},
 {name:"style",type:"asset",data:{type:"css"}}
]

I know that this would be easier:

"topLevel":
[
 new ServiceNode("Clazz1"),
 new AssetNode("style", "css")
]

...but it wouldn’t be portable across JSON-RPC. What if we had a version of the service browser in AJAX?

• Description: Returns all the data associated with a service, including description and method description
• Arguments: serviceName, including the package name, such as com.myPackage.Clazz1
• Returns: an object such as:

{
 name:"com.myPackage.Clazz1",
 description:"This is a clazz that does stuff",
 methods:
 [
  {
   name: "methodName1",
   description: "a method that does stuff. Extra things like author tags and whatnot may be added to description",
   arguments: [{name:"arg1", 
                type:"* for untyped languages, type for typed languages", 
                description:"description if available"}],
   returns: {type:"*", description:"Could return anything"},
   extra: {roles:"admin, user"}
  }
 ]
}

Evert: not sure if ‘roles’ should be in the spec, since I think AMFPHP is the only implementation which actually uses this.. I think most people would go for an ACL list.. At the very least the servicebrowser should not show this field of its not being returned.. How about using “mixed” or “any” for type, instead of “*”

Patrick: updated definition to have “extra” key. Everything in the “extra” field should be appended to the end of the service description in the UI, unless a specific key is recognized and there is code in the service browser to format it accordingly. If extra is null, then don’t do anything.

• Description: Returns the code templates that the service browser implementation supports (if codegen is one of the capabilities)
• Arguments: none
• Returns: An array of templates, like so:

[
 {name:"AS3", description:"AS3 template"},
 {name:"service-config.xml", description:"Services config file, for Flex 2"}
]

• Description: Creates the code for a service, using a template
• Arguments: serviceName, templateName
• Returns: an array of files as strings, like:

[
 {filename:"services-config.xml", data:"XML data"}
 {filename:"views/ServiceShortName_view.mxml", data:"MXML data"}
]

• Description: Saves code to the remote server. Internally calls createCode to generate the code, then uses filename to save to the appropriate place.
• Arguments: serviceName, templateName
• Returns: true on save, triggers a fault on error with faultDetail containing the detail

• Description: Retrieves info about the remote server and Remoting implementation
• Arguments: none
• Returns: A html string, such as:”Amfphp 2.0.1<br/><a href=”http://amfphp.org>amfphp.org</a>”