vqServer API API Overview


The vq.utils package contains utility classes used by vqServer. These classes were not  originally designed for use outwith vqServer and this is reflected in their non-standard naming.

vq.utils.kllist represents a linked list. vq.utils.klentry represents an entry in a linked list. vqServer uses these classes extensively (instead of hashtables, vectors or whatever) and many vqServer classes are descendants of these classes, so some familiarity with them is useful.

The vq.server package contains the vqServer specific classes.

vq.server.console represents a vqServer installation. Most of console's properties and methods are static. console contains utility, startup and shutdown methods, provides control of system-wide settings (like the autosave interval) and provides access to all other vqServer objects.

The remainder of the classes in the vq.server package have a clear relationship with objects that will be familiar to anyone who has used the vqServer control centre. For example vq.server.HttpServer represents an HTTP server, vq.server.Acls represents a list of access control lists such as the list of access control lists displayed by the control centre and vq.server.User represents a user's record in vqServer's user database. Each class has methods which allow its properties to be examined and changed.

For example, assuming you wanted to change the name of a user whose ID was ppan. Call console.getUsers() to obtain the list of users. Invoke Users.getByID(String) on the returned vq.server.Users object to obtain ppan's user record. Use User.setName(String) to change ppan's name.

To create a new user, use the constructor User() to create an empty record, fill out its fields using User.setXxx() methods and use console.getUsers.add(theUser).

The layer which separates the publicly accessible properties and methods of the vqServer API from the underlying functionality is very thin (where it exists at all). The primary design goal was to produce an efficient robust server, not a robust programming environment. It is therefore possible to introduce bugs by inappropriate use of the vqServer API. Your attention is drawn to some potential trouble spots:

  1. The key property of vq.utils.klentry is publicly accessible. Most descendants of vq.utils.klentry in vq.server attach a special meaning to this property. You should not modify it directly (except for instances of vq.server.Parameter).
  2. The kill() method of vq.utils.klentry must not be used while the entry is a member of a list.
  3. Methods of vq.utils.kllist do not check their parameters for list membership. Adding an entry to a list when it is already in another list or removing an entry from a list of which it is not a member is possible but will cause subtle bugs.
  4. It is possible to add any descendant of vq.utils.klentry to any descendant of vq.utils.kllist. For example you can add a vq.server.Parameter to a vq.server.Acls. The compiler won't trap this error but a runtime exception will be thrown the next time vqServer tries to use the list of ACLs.
  5. You can use a number of different add() methods to add entries to the lists defined in the vq.server package but usually only one method is correct. For example, you should only use Users.add(User) to add an instance of vq.server.User to and instance of vq.server.Users.
  6. Call console.setChanged() after making any configuration changes that you want vqServer to save in its configuration file.


vqServer API version 1.9. Copyright © 1997-2000 Steve Shering and vqSoft. Last updated 24 August 1999.

vqSoft
vqServer
API home page

Contents
Download
Registration
FAQs
Support