Konark - Ad-Hoc Service Discovery
The Available APIs fall into these sections:
Registry APIs
The user takes two roles within the Konark protocol: either client or a server. When the user is looking for services, the device acts as a client. When one owns the service that a client wants to invoke, the device takes the role of a server. We will now take a look at the registry APIs for both a client and a server.
Client registry APIs
The client registry APIs exist in Konark.clientservicemanager.ClientServiceManager. This class includes the methods to get the available services discovered in the network. Also, there are methods to get the remaining time left to access these services and one can set what services to look for in discovery.
Konark.clientservicemanager.ClientServiceManager
1. ArrayList getAvailableServices() - This method gets all of the services that have been discovered by this device. All of the services are returned in the form of an ArrayList. One can then manipulate the services for display by casting each element in the ArrayList to AvailableSpecificService.
2. ArrayList getInitServices() - Method that gets the generic services of the service tree. This allows the user to get services other than the leaf nodes which are actual services. By doing this one can decide which available services one wants to display.
3. ArrayList getChildren (string pathToGenericService) - This method gets the children of a given generic service. The string that this method takes describes the registry path to the node.
4. string getServiceURL (string serviceName) - Using this method gets the URL of the service one is interested in. The URL can then be used to get the full description. This method takes the name of the service of interest.
5. int getRemainingTime (string serviceName) - This method returns the number of minutes remaining to access the specified service.
6. bool setInterest (string pathOfInterest) - This method sets the interest to the specified path. This path is given in the form of rootnode:child:nextnode. True is returned if the interest is set successfully, false, if not.
7. bool resetInterest (string pathOfInterest) - Calling this method will reset the interest to all possible service types. True is returned if the interest is set successfully, false, if not.
8. bool setFilter (string pathFilteredOut) - This method sets a filter on the service path to filter out service on this part of the service tree.
9. bool resetFilter (string pathFilteredOut) - Resets the filter to filter out the specified path
Server registry APIs
The server registry APIs are located in the class called Konark.serverservicemanager.ServerServiceManager. These APIs are mainly for creating, managing, and deleting registered services.
Konark.serverservicemanager.ServerServiceManager
1. bool registerService(AppService actualService, string xmlFileName, string pathInRegistry) - This method will register the service with the device that calls it. The service must exist on the device calling this method. A true or false is returned indicating whether or not the method call was successful (true) or not (false).
2. bool unregisterService (string pathInRegistry, string serviceName) - This method will un-register an already registered service. Passing the method the path to the service in the registry and the service name, the service will be deleted from the tree. The actual service will still exist on the device and may be registered again. A true or false is returned indicating whether or not the method call was successful (true) or not (false).
3. ArrayList getServices (string serviceNameOrPath) - Passing either a service name or the path to services in the registry will get two different things. The former returns an ArrayList with one element. The single element is the actual service represented by the passed service name. The path returns an ArrayList with as many services as there are that are leaf nodes to the passed path in registry.
4. void changeServicType (string serviceName, string newServiceType) - Calling this method allows the user to change the service type of an existing service. Simply pass the service name of the intended change and the new type.
5. void changeTimeToLive (string serviceName, int ttl) - This method is called to change a service's time to live.
Discovery APIs
Server-side Service Discovery
These APIs are used by the server device to either wait and listen for another device to ask it what services are available or proactively advertise its currently registered services. The former is known as the pull method, the latter is referred to as the push method. We also use the terms discovery and advertisement, respectively.
Konark.serverservicemanager.ServerServiceManager
1. void startDiscoveryListener() - Using this method one starts a thread that listens for another device to ask it what services are available.
2. void stopDiscoveryListener() - This method is used to stop the listening thread. This is done when the user does not want another device to discovery its services by the pull method.
Konark.serverservicemanager.ServerAdvertisement
1. void performAdvertising (string pathInRegistry) - This method is used to push the services on the other devices in the network. By passing in the path in the registry of what kind of services one wants to advertise, all of the services at this path in the registry will be sent to a multicast address where all of the devices in the network can "see" them.
Konark.serverservicemanager.ClientRequestHandler
1. ClientRequestHandler.ClientRequest+= - When this command is typed, the user will be prompted for the rest of it, hit "Tab" then hit "Tab" again and Visual Studio will automatically write the method signature for you. This event is fired to transfer control back to the main thread, so I would advice writing nothing in the body of the event method. However, one may do what they like with this event and may signal to the user that someone is attempting to access their services.
Client-side Service Discovery
These APIs are used by the client device to receive advertisements and to actively discover services using discovery. There are two classes associated with these APIs.
Konark.clientservicemanager.ClientServiceManager
1. void startAdvertisedListener() - This method is used to spawn a thread that will listen for advertisements from another device.
2. void stopAdvertisedListener() - When the user does not want to receive any advertisements of services, she may stop the advertisement listener thread.
Konark.clientservicemanager.ClientDiscovery
1. void discover(string pathInRegistry) - This method spawns a new thread which runs another method. The second method sends a discovery message for all services in the specified path in the remote device's registry and waits for any replies. This method takes as a parameter the types of services it wishes to discover.
Konark.clientservicemanager.AdvertisedServiceHandler
1. AdvertisedServiceHandler.ServiceHandler+= - When this command is typed, the user will be prompted for the rest of it, hit "Tab" then hit "Tab" again and Visual Studio will automatically write the method signature for you. You will need to fill in the body of the event handler method. When a service is discovered, an event is fired and can be caught by the main application or GUI. By filling in the even handler method, one can control what she wants to do with the new service.
Delivery APIs
HTTP Server for receiving Service Invoke
These APIs are used to start and stop the HTTP server on every Konark device. The server is responsible for handling requests for the full description of a service and finally the service invoke.
Konark.HTTP.Server.
1. void start() - This method starts the HTTP server.
2. void stop() - This method stops the HTTP server.
Client-side Service Invoker
These classes deal with methods to start and complete service delivery from the client's device.
Konark.deliverutils.ServiceInvoker
1. void invokeMethod (UsableService service, string methodName, ArrayList inParameters, ArrayList outParameters) - This is the method used by the client to invoke a service on a remote device. This parameters for this method are all collected from the previous step in the protocol which is getting the full service description, which includes downloading the XML description of the service.
2. UsableService getFullServiceDescription (string Url) - This method makes a request to a remote HTTP server for the XML description of the requested service. This method takes a string representation of the url of the requested service. The return value is of the class UsableService. With this, one can make SOAP requests on the remote HTTP server.
3. ServiceInvoker.ServiceInvokerHandler+= - This is an event handler that will be called after an event is fired from the method invokeMethod (above) when it gets a response from the server successfully.
4. FullDescriptionHandler+= - This is an event handler that will be called after an event is fired from the getFullServiceDescription method (above). The event is fired after this firing method gets a response from the server successfully.
Konark.descutils.UsableService
1. Function getFunction() - Returns the functions associated with this service.
2. string getURL() - Returns a string representation of the URL of this service.
3. void setServiceType(string Type) - Sets the service type of this usable service.
4. string getServiceType() - Gets the service type from this usable service.
5. void setDuration(string duration) - Sets the duration this usable service is available.
6. string getDuration() - Gets the duration this usable service is available.
7. void addKeyword(string key) - Adds a keyword to the usable service, makes it easier to be found.
8. ArrayList getKeywords() - Gets the keywords from the usable service.
9. string getKeyword(int index) - Returns the keyword from the specific index.
10. bool containsKeyword(string key) - Returns TRUE if the keyword is contained in this usable service, otherwise returns FALSE.
11. void setServiceName(string name) - Sets the usable service's name.
12. string getServiceName() - Returns the usable service's name.
Konark.descutils.Function
1. string getDescription() - Returns a brief description of the function.
2. void setReturnParameter(string Name, string Type, string Description) - Sets the return parameter.
3. Parameter getReturnParameter() - Gets the return parameter for the function.
4. ArrayList getInParameters() - Gets an array list of the input parameters for the function.
5. string getName() - This method returns the function name.
Konark.descutils.Parameter
1. string getParameter() - Gets the parameter's name.
2. string getType() - Returns the type on the parameter. The three types available for Konark are Int, String, and File.
3. string getDescription() - Returns a brief description of the parameter.