<previous | top | next> Pyro Manual

5. Pyro Naming Service

Pyro's hierarchical object naming scheme

Brief: it's just like a filesystem with directories and files, and path separators.
Verbose: Pyro's object naming is hierarchical. Let's call the full set of names the namespace. A namespace has a single root that contains all other names. A name in the namespace is the name of a group or an object. A group can contain other groups, and objects. The root is a group.

Object names can be absolute or relative. Relative object names are searched in the default group (which has a special name, set by PYRO_NS_DEFAULTGROUP). Absolute names are always searched from the root. Absolute object names start with a special character that signifies the root (set by PYRO_NS_ROOTCHAR). Relative object names don't have this character at the start.

Object names can be simple or compound. Compound object names consist of multiple parts separated by a special group separator character, set by PYRO_NS_GROUPSEP. Compound names are used to search within the namespace hierarchy. Each component of the name is the name of a group. The last name component can be the name of a group or an object (usually the latter).

Let's finish with a few examples to clarify all this. Note that by default, the root character is ':' and the group separator is '.'. Note that by name alone you cannot distinguish a group name or an object name.
: The namespace root group
:TestObj The TestObj name in the root (most likely an object name)
:Test.simple.object1 The object1 name in the simple group in the Test group in the root.
Test.simple.object1 The object1 name in the simple group in the Test group in the default group (which is ":Default" if not configured otherwise. This is the Default group in the root).
object1 The object1 name in the default group.

The different naming server types available

There are two kinds of Name Servers available at the moment: The non-persistent NS stores its naming database only in memory. It is really fast because of that, but when it stops or crashes, the naming database is lost. All objects that were registered in the NS have to be re-registered.

The persistent NS stores its naming database on disk. Currently this is implemented the easy way; there is a direct mapping between the group names and directories on disk, and between object names + URI's and files in these directories on disk. The database by default is stored in a "Pyro_NS_database" directory that is created in the directory configured by PYRO_STORAGE. There is a special option for the script that specifies another location, if needed. See below.

Usually you don't access the NameServer or PersistentNameServer classes directly: there are scripts to start the right name server.

Connecting objects to the Pyro Daemon with persistent naming

Usually you'll use the connect method of the daemon to connect your object instances to the daemon on the server. The daemon will register your object with the name server too, if you supplied a NS to the daemon and your object isn't transient (it has a name).

But, when using the persistent name server, there is a complication here: if you didn't explicitly remove your object from the NS, the entry will still be there the next time. Your connect attempt will then fail because your object cannot be registered again in the NS.

The solution is to use the new connectPersistent method of the Pyro daemon. Except for the method name, you call it exactly like the regular connect method. It tries to find your object in the NS. If it's there already, the previous URI is used for your object (that also means that the object's GUID is replaced by the previous GUID that was found in the NS). If it isn't there, the regular connect call takes over.

Of course you could always play safe and explicitly unregister any possible previous occurrences from the NS before you connect new instances. This is what all examples do by the way, so you can safely run an example again and again.

For your information, the code that starts the Persistent Name Server uses connectPersistent to connect the name server object to the daemon. Why? because the name server itself is also registered in the NS database, and it is necessary that when the NS restarts, it uses the URI of the previous instance if found in the persistent database.

Security plugin features

Since version 2.0 Pyro has connection validators, see the Features chapter for more info. The Name Server also has some new properties regarding validators. When starting the NS, you can supply an option that tells the NS to load that specific Python module and use the security plugins that you defined in there. What is possible? You'll have to write a Python module that contains the following: When you start the NS using the '-s' switch, it will read your module and call the two functions mentioned above to get your validator objects. The NS prints their names to show that it's using them and starts. Have a look at the "NS_sec_plugins" example to see how things are done.

The commands for starting a Name Server

There are a few commands (actually scripts) supplied in the bin directory that will start a Pyro Name Server for you:
ns   (Naming Server)
- Arguments: [-h] [-k] [-n hostname] [-p port] [-b port] [-d [databasefile]] [-s securitymodule]
- Starts the Pyro Naming Service. The '-h' argument prints some help, '-k' makes it immune to shutdown requests (a crude form of security against malicious shutdown requests), '-n hostname' selects the hostname the server should bind on (useful on systems with multiple network adapters/hostnames), '-p port' specifies the Name Server port number, '-b port' specifies the broadcast port number, and '-d' starts the persistent server. You can provide an optional filename to the last option to specify the database file. The '-s' option specifies the Python module for security plugins.

rns   (Restarting Naming Server)
This is very much the same as the ns command but the script will restart the name server if it quits or crashes. Do not confuse this with the -d argument, which will start a naming server that has its database persistent on disk. Of course it is very useful to combine the rns with the -d switch!!!

ns.bat, rns.bat
The Windows scripts for the above.
Using the nsc command (explained in the Usage chapter) you can control a Name Server that is already running.