| Support | Home | Word |
|
|
PageBox |
|
|
|
|
|
|
| Presentation | User guide | Token API | Active naming | Extensions | Implementation | Token implementation |
Active Naming user guideObjectiveThis document explains how to use the Active Naming methods of the PageBox API to allow:
AudienceArchive developers. PrincipleThe principle of Active Naming and its applications are exposed in an Active Naming presentation. Servers declare entry points and clients ask for the most appropriate implementation of these entry points. An entry point has a logical name and three pieces of information:
The "must" object must implement the Serializable interface. The Active Naming implementation uses the equals method to decide if a service instance "must" matches the "must" object provided by the client. The "niceif" object must implement an ActiveComparable interface defined like this:
Where o is a niceif object and usage is an object of ResourceUsage class that describes the resource usage on the PageBox hosting the service. This class is defined like this:
MemUsage is defined like this:
Where:
The Active Naming implementation uses the compareTo method to mesure the distance between the "niceif" object provided by the client and the "niceif" objects of the service instances whose "must" objects were found equal. Then the Active Naming implementation randomly chooses a service instance in a list where
PageBoxAPIA Web application acting as a client uses:
A Web application instance acting as a server uses:
ActiveNamingLogonSignature: void ActiveNamingLogon(); A Web application must call ActiveNamingLogon before using the getEntries and getCandidate methods. A Web application should call ActiveNamingLogon as soon as it is sure that it will act as a client because Active Naming uses the Token API. Therefore after logon it will take up to token-period before getEntries and getCandidate will return valid responses. In doubt logon when you create your PageBox API instance:
ActiveNamingLogoffSignature: void ActiveNamingLogoff(); A Web application should call ActiveNamingLogoff when it won’t use anymore the getEntries and getCandidate methods. The application should call ActiveNamingLogoff at least when it is unloaded. To monitor unloads a Web application can implement the destroy method on a servlet as demonstrated in the Prometheus example. getEntriesSignature: String[] getEntries(); getEntries returns the logical names of entries declared by Web application instances everywhere on the ring and null when:
getCandidateSignature: String getCandidate(String name, Serializable must, ActiveComparable niceif); getCandidates returns the URL (Web service, page) of the most appropriate service instance given:
getCandidate returns null when:
addEntrySignature: void addEntry(String name, Serializable must, ActiveComparable niceif, String url); addEntry declares an entry point with the following parameters:
To call addEntry a Web application doesn’t need to call ActiveNamingLogon. Active Naming automatically registers to the ring when needed. If the Web application calls again addEntry with the same logical name then the entry is updated. removeEntrySignature: void removeEntry(String name); removeEntry removes an entry point identified by its logical name. If then the Web application has no more entry points and if this Web application didn’t call ActiveNamingLogon the Active Naming un-registers from the ring. clearEntriesSignature: void clearEntries(); clearEntries removes all entry points declared by the Web application. If the Web application didn’t call ActiveNamingLogon, the Active Naming un-registers from the ring. AdvicesLook at Prometheus for an example of use of Active Naming. must and niceif semanticmust is about imperative matching. For instance to implement data dependent routing you must use must and not niceif even if you check if a query value is in a range. niceif is about biased or weighted load balancing. The distance returned by compareTo is used to weight the service instance. Closest a service niceif is to a queried niceif more chances this service instance has to be chosen. mustThe queried and the service musts are compared with the equals method. Usually equals is commutative: if xxxx.equals(yyyy) is true then yyyy.equals(xxxx) is also true. Though you can always implement commutative equals this is not required by Active Naming. The comparison is made with the following code for each service instance:
Where must is the queried must and omust is the service must. If the requestor has a non null must services whose must is null are ignored. Active Naming always calls the equals method of the queried must. In the common case where you use Active Naming for data dependent routing with value ranges you can code must in the following way:
This implementation is commutative and use a single object – though with two different constructors. For more complex implementations you can use two different objects, one for the declaration of service instances and one for queries. niceifThe queried and the service niceifs are compared with the compareTo method. compareTo returns an signed integer. Active Naming ignores the sign because it measures a distance. In your implementation avoid large numbers. In many cases a compareTo that returns 0 or 1 is enough. The comparison is made with the following code for each service instance:
Where niceif is the queried must, oniceif is the service niceif and me.ru is the ResourceUsage object of the PageBox hosting the service or null if the hosting PageBox failed to collect data. Active Naming always calls the compareTo method of the queried niceif. The compareTo method should check the validity of the ResourceUsage fields. Five fields of ResourceUsage should be set up:
Other fields are set up depending on the Operating System and Java Virtual Machine capabilities. When a long field is not set up its value is -1. When a float field is not set up its value is Float.NEGATIVE_INFINITY.
Contact:support@pagebox.net |
|