The PageBox ActiveNaming involves four participants:

• The client. It wants to know the Web Service instances that it can call.

• The client PageBox. The client doesn’t know the PageBox constellation. It only knows its controlling PageBox that acts as a client PageBox

• The Web service or a facility that acts on behalf of the Web Service. It knows the requests that it can serve.

• The Web service PageBox. The Web service doesn’t know the PageBox constellation. It only knows its controlling PageBox.

Web Services can record an arbitrary string, keyRange that can help for routing.

For data dependent routing keyRange can actually be a key range or a set of key ranges.

To record this information, a Web Service uses the SetKeyRange method of the ActiveNaming Web service. The Web Service can also use SetKeyRange to update the keyRange string.

Before being de-installed a Web Service should call a RemoveKeyRange method (not depicted on the diagram) of ActiveNaming.

SetKeyRange and RemoveKeyRange persist keyRange updates in a keyRanges.xml file.

Note:

keyRange is a string. This string can be an object serialized with a serializer such as XmlSerializer, SoapFormatter or BinaryFormatter. SoapFormatter or BinaryFormatter are easier to use.

Prefer the SoapFormatter in cases where you need to read the data for instance for troubleshooting.

The XmlSerializer is useful when you need to read and update the data manually, which shouldn’t be the case for keyRange.

The SoapFormatter is easy to use. Here is an example of serialization:

Here is an example of deserialization:

When we designed the API we had the choice between three types for keyRange:

• object. Drawback: the SOAP proxy cannot serialize any kind of object. We need to provide a wrapper class on top of the proxy

• byte array. Drawback: the keyRange typically stores a small amount of information. Very often a Comma Separate Values (CSV) format is enough and string is the best class to create and parse such data

• string

Therefore we chose to define keyRange as a string.

Web service clients use the GetCandidate method of the ActiveNaming Web service to get the list of the available instances of the Web service and for each instance

1. Its URL

2. Its keyRange string

A Web service calls the GetCandidate method of its controlling PageBox.

GetCandidate first tries to find the list in an Active cache.

If it doesn’t find an applicable list or if this list has expired, GetCandidate calls the GetSubscribers method of the Repository RepoQuery Web service.

GetSubscribers returns the URLs of the PageBoxes that installed the Web service.

1. Then GetCandidate calls the GetKeyRange method of each PageBox that installed the Web service and Builds a list of candidates with their URL and keyRange

2. Stores the list in the Active cache

3. Returns the list

If the Repository is not running, GetCandidate retrieves the list from the Active cache even if the entry has expired.

An ActiveNaming Web service maintains a Hashtable of keyRange, activeNames.

The key of activeNames entries is an ArchiveService object.

ArchiveService has two fields:

• WebService_archive. Name of the archive where the Web service was packaged.

• WebService_name. Name of the Web service.

The value of activeNames entries is the keyRange string.

activeNames is restored from keyRanges.xml by the ActiveNaming constructor and saved by the methods that change its content, SetKeyRange and RemoveKeyRange.

An ActiveNaming Web service maintains a candidate Hashtable, cache.

The key of cache entries is a repository URL because a client PageBox can return candidates from different Web service repositories.

The value of cache entries is an archCache Hashtable.

The key of archCache entries is the name of the archive where the Web service was packaged.

The value of WSCache entries is a WSCache Hashtable.

The key of WSCache entries is the name of the Web service.

The value of WSCache entries is a CacheEntry object.

A CacheEntry object contains two fields:

• expiration. Time when the cache entry becomes invalid.

• candidates. An array of Candidate objects. The Candidate class is described below.

This organization allows to quickly finding a Candidate array with the three fields that fully define a Web service:

• The Repository name

• The name of the archive where the Web service was packaged

• The name of the Web service

cache is restored from activeCache.xml by a restoreCache method and saved by SetCandidateInCache.

Function:

Set the keyRange string that applies to a Web Service instance.

Signature:

void SetKeyRange(string WebService_archive, string WebService_name, string keyRange);

Parameters:

WebService_archive: Name of the archive where the Web service was packaged

WebService_name: Name of the Web Service

keyRange: string that can be used to select a Web service instance, for instance for data-dependent routing

Implementation:

SetKeyRange adds or updates an activeNames entry with a new keyRange string.

Function:

Remove the keyRange string of a Web Service instance.

Signature:

bool RemoveKeyRange(string WebService_archive, string WebService_name);

Parameters:

WebService_archive: Name of the archive where the Web service was packaged

WebService_name: Name of the Web Service

Implementation:

RemoveKeyRange removes an activeNames entry.

RemoveKeyRange returns false if there is no activeNames entry with this (WebService_archive, WebService_name) and true if it removed an activeNames entry.

Function:

Retrieve the keyRange string that applies to a Web Service instance.

Signature:

string GetKeyRange(string WebService_archive, string WebService_name)

Parameters:

WebService_archive: Name of the archive where the Web service was packaged

WebService_name: Name of the Web Service

Returned value:

A keyRange string that can be used to select a Web service instance, for instance for data-dependent routing.

Implementation:

GetKeyRange retrieves and returns a keyRange string.

It returns null if there is no activeNames entry with this (WebService_archive, WebService_name).

Function:

Retrieve the URLs of the Web service instances providing a Web service.

Signature:

Candidate[] GetCandidate(string repository_URL, string WebService_archive, string WebService_name);

Parameters:

repository_URL: Repository where the Web service has been published

WebService_archive: Name of the archive where the Web service was packaged

WebService_name: Name of the Web Service

Returned value:

An array of Candidate objects.

Candidate definition:

Where url is the URL of the Web service and keyRange is an string that can be used to select a Web service instance, for instance for data-dependent routing.

Implementation:

GetCandidate first tries to find the Candidate list in cache using the GetCandidateFromCache method.

GetCandidateFromCache has a signature:

Candidate[] GetCandidateFromCache(string repository_URL, string WebService_archive, string WebService_name, bool force);

If the force parameter is set to false, which is the case when GetCandidateFromCache is invoked at the beginning of GetCandidate, GetCandidateFromCache returns a Candidate list if

1. It is defined for (repository_URL, WebService_archive, WebService_name)

2. It is not expired (not in cache for more than two hours)

If GetCandidateFromCache found no valid list, GetCandidate calls the GetSubscribers method of RepoQuery to retrieve the list of the PageBoxes that installed WebService_archive. Then for each PageBox found GetCandidate calls a GetCandidate2 method.

GetCandidate2 calls the GetKeyRange method of the PageBox ActiveNaming Web service and returns the keyRange for (WebService_archive, WebService_name).

Once it has built the Candidate list GetCandidate calls SetCandidateInCache to save the list in cache and returns the list.

If the invocation of GetSubscribers fails, GetCandidate tries to retrieve a cache entry from the cache, regardless of the expiration time using GetCandidateFromCache with force = true.

ActiveNaming is primarily designed to allow implementing load balancing and routing.

Three models are possible:

1. Load balancing. keyRange is not used. The load balancing facility returns one Web service URL among the Candidate list, for instance using round robin.

2. Closest instance routing. keyRange can be used to specify an area. Given the client area the routing selects the best matches. It is also possible to compare the IP addresses of the Web service and of the client to select the best match.

3. Data dependent routing. keyRange specifies for instance parameter ranges. When a Web service method is invoked the content of some parameters is used to select the most suitable Web service instances.

All combinations of the three models can also be used. Look at Polaris for an implementation of the three models.

ActiveNaming can also be considered as a facility allowing associating name value pairs to the archives.

In this case WebService_name is no longer the name of a Web service but any name meaningful in the context of a Web Archive. In the same way keyRange is no longer information for routing but any kind of value.

The Grid API is an example of such a use of ActiveNaming.

Contact:support@pagebox.net
©2001-2004 Alexis Grandemange. Last modified .