Essential Guidelines

It is essential to set the groups and locators system properties in the Java process which starts the Lookup Service or Mahalo services. This is required in order to "tell" the Jini service which groups and locators it should join, and which to serve. If these properties are not set, the Lookup Service/Mahalo uses the Jini fallback values and that impact the SLA these services serve with.

Do not have more than two Jini Lookup Services across one site – having the gsInstance running a Jini Lookup Service embedded by default can cause problems. As a result of not have more than two Jini Lookup Services across one site, spaces do not have to deal with registering themselves into too many Jini Lookup Services, and the Space Browser's freezing behavior is reduced.

Jini groups vs. locators – Jini groups are irrelevant when using unicast lookup discovery – they are relevant only when using multicast lookup discovery. If you have multiple spaces with the same name and you are using unicast lookup discovery, you might end up getting the wrong proxy.

In such a case, make sure you have a different lookup group for each space, where each space is configured to use a specific lookup. A good practice is to have different space/service names.

Setting up the Lookup Service Group

Each of the Jini Services (such as the Reggie lookup service or the Mahalo Transaction Manager) registers and advertises using a group name which is defined by the following system property (set in the /bin/setenv.bat file):

set LOOKUPGROUPS="gigaspaces-%USERNAME%"
set LOOKUP_GROUPS_PROP=-Dcom.gs.jini_lus.groups=%LOOKUPGROUPS%

While the %USERNAME% will be replaced after installation with the version number e.g.
set LOOKUPGROUPS="gigaspaces-6.0XAP".

The command that loads a space needs to have this system property set. Another way of doing it instead of setting the com.gs.jini_lus.groups system property, is to set the Space URL groups attribute, e.g.:

/./mySpace?schema=cache&groups=myPrivateGroupName

How do I Use/Set Unicast (Jini Locators) Discovery?

There are many cases when you need to use a unicast-based services discovery, for example if you want to use unicast with multicast (using Jini Groups) or when you do not have multicast enabled on your machine, or you prefer not to use multicast.
In such case the Jini lookup discovery enables the user to discover services (spaces, GSC, GSM, processing units etc.) using unicast protocol.

Disabling Jini Multicast Discovery By default - the multicast and unicast discovery are always turned on. XAP 6.5 and onwards supports the ability to disable the Jini multicast discovery.

What Should I Change in Order That Services will be Found Using Jini Unicast Protocol?

In order that the services (spaces, GSC, GSM, processing units etc.) will be found using Jini Unicast protocol, you will need to do the following:

• Go to bin/setenv.sh/bat shell file and set a comma separated list of hosts:ports in the LOOKUPLOCATORS variable (or -Dcom.gs.jini_lus.locators system property). This list should include the hosts where the Jini Lookup Service (or GSM) are running and their port which is 4160 by default.

if "%LOOKUPLOCATORS%" == ""  (
set LOOKUPLOCATORS=linux-lab1:4160,linux-lab2:4160
)
set LOOKUP_LOCATORS_PROP=-Dcom.gs.jini_lus.locators=%LOOKUPLOCATORS%

In the example above, the GSM/LUS should run on linux-lab1:4160 and linux-lab2:4160 machines.

What should I Change in Order to Find a Service Using Jini Unicast Protocol?

Once the services (spaces, GSC, GSM, processing units etc.) already started with the -Dcom.gs.jini_lus.locators settings then any client should be able to find it using unicast discovery.

Do the following in order to "tell" the client to lookup a service using a unicast protocol:

• Each of the clients should add locators SpaceURL attribute to the space url string it uses in order to find the service.

E.g. for unicast AND multicast discovery

jini://*/./mySpace?locators=linux-lab1:4160,linux-lab2:4160&groups=gigaspaces-6.0XAP

jini://linux-lab1:4160,linux-lab2:4160/./mySpace?locators=linux-lab1:4160,linux-lab2:4160

Note that the default discovery is both unicast and multicast, therefore in the above example once having locators attribute AND jini://* prefix but also groups attribute, the discovery will be unicast AND multicast. The second example, does not use multicast for discovery.

For troubleshooting purposes you should verify that the services (spaces, GSC, GSM, processing units etc.) print a correct settings for the locators while they initialize. You can turn on the relevant logging if required.

Changing Jini Lookup Service (or Mahalo) Unicast Port

1. To change the lookup service port when using the Service Grid, use an override. For example, if the machine you are using is pc-lab:1234:

   <overrides>
       <component Name="com.sun.jini.reggie">
           <parameter Name="initialUnicastDiscoveryPort" Value="1234"/>
       </component>
   </overrides>

   If you are not using the Deployment Descriptor or are just starting a Lookup Service instance (running startJiniLUS); modify the com.sun.jini.reggie block in the /services/services.config file, specifying the port of the unicast locator which the Lookup Service is initialized with:

   //Specifies the initial number of the port on which to listen for unicast discovery queries. 
   //If the port number is 0, then an arbitrary port is selected (with preference given to 4160, if available). 
   //This entry is obtained once at service start
   initialUnicastDiscoveryPort = 1222;

   For more details, see Reggie JavaDoc.

2. Set the LOOKUPLOCATORS system property in <GigaSpaces Root>\bin\setenv.bat/sh to match the port number you defined (in this case, pc-lab:1234). That is required if you specify an explicit unicast/locators port, otherwise the service will use the 4160 port if not set explicitly.

For details on how to start an embedded Mahalo (Jini Transaction Manager), refer to the gsInstance section.

Troubleshooting the Discovery/Group Configuration

Using the list LUS CLI option, run from <GigaSpaces Root>\bin\gs.bat/sh, you can search for available Jini Lookup Services in the network.

Since GS 6.0.2:
<GigaSpaces Root>\bin\gs.bat/sh list lus

The following result examples appear on the console:

-----------------------------------------------------------------------
-- Discovered Lookup Service at host [ 192.168.10.233 ].
-- Lookup Service registered to the following jini groups:
                 Group [ gigaspaces-gershon ]
-- Lookup Service has [3] services, lookup took [631] millis, [0] seconds:
                 Service Class: com.j_spaces.core.JSpaceContainerProxy | 018aae08-5d2a-4b61-9739-36c915f4e2d9
                 Service Class: com.j_spaces.core.client.JSpaceProxy | 6f05db92-187f-4e26-b52d-ec32d3d4723c
                 Service Class: com.sun.jini.reggie.ConstrainableRegistrarProxy | 2ff6aab3-8e1a-4a2b-a1b2-
                 4391825c2bbc
 
-----------------------------------------------------------------------
-- Discovered Lookup Service at host [ 192.168.10.233 ].
-- Lookup Service registered to the following jini groups:
                 Group [ gigaspaces-gershon ]
-- Lookup Service has [3] services, lookup took [50] millis, [0] seconds:
                 Service Class: com.j_spaces.core.JSpaceContainerProxy | 018aae08-5d2a-4b61-9739-36c915f4e2d9
                 Service Class: com.j_spaces.core.client.JSpaceProxy | 6f05db92-187f-4e26-b52d-ec32d3d4723c
                 Service Class: com.sun.jini.reggie.ConstrainableRegistrarProxy | d3e7e224-9b46-4782-a902-
                 e4e64c11ca95

For details on viewing the exact configuration in which the system is currently running, refer to the Container Maintenance section.

Multi Network Card Configuration

The configs/services/services.config contain a specific setup for Multi-NIC interfaces (as part of the net.jini.discovery.LookupDiscovery and Reggie/Mahalo blocks).

For more details on multi-network card configuration, refer to: Multi-NIC Configuration.