[[nameregistrar]]

== NameRegistrar

*org.jpos.util.NameRegistrar* is a very simple *singleton* class that can be
used to register and locate jPOS components.  

It's nothing but a simple, well-known Map where one can easily find components
by an arbitrary name. 

NameRegistrar has the following static methods: 

[source,java]
----

    public static void register (String key, Object value);
    public static void unregister (String key);
    public static Object get (String key) 
        throws NameRegistrar.NotFoundException;
    public static Object getIfExists (String key);
  
----

So you can write code like this: 

[source,java]
----

   ...
   ...
   ISOMUX mux = new ISOMUX (...);
   NameRegistrar.register ("myMUX", mux);
   ...
   ...
  
----

and elsewhere in your application you can get a reference to your MUX with code like this: 

[source,java]
----

     try {
        ISOMUX mux = (ISOMUX) NameRegistrar.get ("myMUX");
     } catch (NameRegistrar.NotFoundeException e) {
        ...
        ...
     }
  
----

 or 
 
[source,java]
----

    ISOMUX mux = (ISOMUX) NameRegistrar.getIfExists ("myMUX");
    if (mux != null) {
        ...
        ...
    }
  
----

Although we can use NameRegistrar in order to register jPOS components,
sometimes it's better to use the component's setName(String name) method when
available. 

Most components have a setName (String name) method implemented like this: 

[source,java]
----

    public class ISOMUX {
        ...
        ...
        public void setName (String name) {
            this.name = name;
            NameRegistrar.register ("mux."+name, this);
        }
        ...
        ...
  
----


The prefix +"mux."+ is used here in order to avoid a clash of names in the
registrar between different classes of components using the same name  (e.g.
+"mux.institutionABC"+  and  +"channel.institutionABC"+). 


Different components use different prefixes as shown in the following table: 

.NameRegistrar's prefix
[cols="2,2,4", options="header"]
|===============
|Component|Prefix|Getter
|ConnectionPool|"connection.pool."|N/A
|ControlPanel|"panel."|N/A
|DirPoll|"qsp.dirpoll."|N/A
|BaseChannel|"channel."|BaseChannel.getChannel
|ISOMUX|"mux."|ISOMUX.getMUX
|QMUX|"mux."|QMUX.getMUX
|ISOServer|"server."|ISOServer.getServer
|KeyStore|"keystore."|N/A
|Logger|"logger."|Logger.getLogger
|LogListener|"log-listener."|N/A
|PersistentEngine|"persistent.engine."|N/A
|SMAdapter|"s-m-adapter."|BaseSMAdapter.getSMAdapter
|===============


[TIP]
====

While we try to keep the previous prefix table up to date, we suggest that
you double-check it against the source code if you have problems getting
references to your components.
====

Using the getter (when available) lets us write code like this: 

[source,java]
----

     try {
        ISOMUX mux = ISOMUX.get ("myMUX");
     } catch (NameRegistrar.NotFoundeException e) {
        ...
        ...
     }
  
----

that will in turn call +NameRegistrar.get ("mux.myMUX")+. Later, we'll see that
NameRegistrar is extensively used by jPOS' Q2 applications. Q2 takes care of
configuring several jPOS components for you, but your code will have to locate
them by a given name. That's where +NameRegistrar+ comes in to play. 

[WARNING]
=========
Singletons are usually an illusion, you think there's just one, but there might be
more than one. If you have multiple classloaders in your application you may end up with 
multiple copies of a singleton, such as the NameRegistrar. 

This problem does not exist if you run Q2 as a stand-alone application.
=========

[TIP]
====
The +NameRegistrar+ is a +Loggeable+ object (see <<logger>>) so its instance
(+NameRegistrar.getInstance()+) can be added to a +LogEvent+ in order to assist
you during debugging sessions. 

When running in a *Q2* environment we recommend to deploy a +sysmon+ service in
order to regularly view the NameRegistrar's content. 
====