GT 4.2.1 RLS : Developer's Guide

A connection source is needed in order to establish connections to the RLS. The connection source may be shared and is a thread safe object. The SimpleRLSConnectionSource may be directly instantiated by the client or it may be used as a JNDI object and shared by multiple clients (e.g., in a container that supports JNDI). In this example, the client instantiates the connection source.

                RLSConnectionSource source = null;
                try {
                    source = new SimpleRLSConnectionSource();
                } catch (RLSException e) {
                    // handle exception
                }
            

Use the connection source to establish a connection. If the source has defaults you may use its parameterless connect() method, otherwise you must supply the connection URL and credentials.

                RLSConnection connection = null;
                try {
                    connection = source.connect(url, credential);
                } catch (RLSException e) {
                    // handle exception
                }
            

The RLS catalog supports creating and adding mappings as distinct operations. A mapping is an association between a logical name and a target name. A logical name or target name is implicitly created when the first mapping between the logical name and a target name is created. For the first such mapping, the create operation must be used. Subsequent mappings between the logical name and other target names may be added using the add operation. Likewise, the logical name is implicitly deleted when the last mapping it appears in is removed.

                // Creates
                List creates = new List();
                creates.add(
                        new Mapping("my-logical-name-123", "ftp://foo/"));

                // Adds
                adds.add(
                        new Mapping("my-logical-name-123", "ftp://bar/"));

                try {
                    LocalReplicaCatalog catalog = connection.catalog();

                    List createResults = catalog.createMappings(creates);
                    List addResults = catalog.addMappings(adds);

                    // The results lists contain MappingResult objects. Each
                    // MappingResult object indicates an error with a result
                    // code. If all mappings succeed, the lists will be empty.

                } catch (RLSException e) {
                    // handle exception
                }
            

Query objects are used to represent different types of RLS queries. There are simple queries, batch queries, and attribute searches. This examples uses a simple query object. We begin by querying the RLS index service which tells us which catalog services to query for a given logcial name.

                IndexQuery indexQuery = new SimpleIndexQuery(
                    SimpleIndexQuery.queryMappingsByLogicalName,
                    "my-logical-name-123",
                    null);
            

RLS index services keep an index of logical names for each catalog service that sends its index to the given index service. By querying an index service, the client can find out which catalog services may have replica locations for a desired logical name.

                try {
                    ReplicaLocationIndex index = connection.index();
                    Results results = index.query(indexQuery);
                    if (results.getRC() == RLSStatusCode.RLS_SUCCESS) {
                        List batch = results.getBatch();
                        Iterator i = batch.iterator();
                        while (i.hasNext()) {
                            IndexMappingResult result = (IndexMappingResult) i.next();
                            if (result.getRC() != RLSStatusCode.RLS_SUCCESS)
                                continue;
                            String logicalName = result.getLogical();
                            String catalogURL = result.getCatalog();
                            // At this point, the client will need to create
                            // a CatalogQuery object for each distinct catalog
                            // URL returned in the results. These URLs indicate
                            // the catalog services which have replica locations
                            // for the given logical name.
                        }
                    }
                } catch (RLSException e) {
                    // handle exception
                }
            

Based on the results of the index query, a client will create catalog queries.

                CatalogQuery catalogQuery = new SimpleCatalogQuery(
                    SimpleCatalogQuery.queryMappingsByLogicalName,
                    "my-logical-name-123",
                    null);
            

The catalog also supports wildcard queries. Use the '%' character for the wildcard.

                CatalogQuery catalogQuery = new SimpleCatalogQuery(
                    SimpleCatalogQuery.queryMappingsByLogicalNamePattern,
                    "my-logical-name-%",
                    null);
            

RLS catalog services keep a catalog of logical names mapped to target names. The target names are typically used to indicate the URL for a data object (e.g., a gsiftp, http, etc. URL).

                try {
                    LocalReplicaCatalog catalog = connection.catalog();
                    Results results = catalog.query(catalogQuery);
                    if (results.getRC() == RLSStatusCode.RLS_SUCCESS) {
                        List batch = results.getBatch();
                        Iterator i = batch.iterator();
                        while (i.hasNext()) {
                            MappingResult result = (MappingResult) i.next();
                            if (result.getRC() != RLSStatusCode.RLS_SUCCESS)
                                continue;
                            String logicalName = result.getLogical();
                            String targetName = result.getTarget();
                            // At this point, the client has resolved the 
                            // target name for the given logical name. Keep in
                            // mind that in the RLS, a logical name may be
                            // mapped to multiple target names.
                        }
                    }
                } catch (RLSException e) {
                    // handle exception
                }
            

RLS also supports attributes on objects (logical names and target names) in the catalog. Before assigning attributes to objects, attributes must be defined.

                List defs = new List();

                // Define a string attribute
                defs.add(new RLSAtribute(
                        "label", 
                        RLSAttribute.LRC_PFN, 
                        RLSAttribute.STR, 
                        null));

                // Define an integer attribute
                defs.add(new RLSAtribute(
                        "series", 
                        RLSAttribute.LRC_PFN, 
                        RLSAttribute.INT, 
                        0));
                
                try {
                    catalog.defineAttributes(defs);
                } catch (RLSException e) {
                    // handle exception
                }
            

Defined attributes may be undefined, and (optionally) all assigned attributes of the matching type may be cleared.

                try {
                    catalog.undefineAttributes(defs, true);
                } catch (RLSException e) {
                    // handle exception
                }
            

Attributes may be added to objects (logical names or target names) in the catalog. Before adding an attribute, it must be defined. Once added, it may be modified or removed.

                List attributes = new List();

                // Add a string attribute
                attributes.add(new RLSAttributeObject(new RLSAttribute(
                        "label",
                        RLSAttribute.LRC_PFN,
                        "my-label-value"),
                        "my-target-name-XYZ));

                // Add an integer attribute
                attributes.add(new RLSAtributeObject(new RLSAttribute(
                        "series", 
                        RLSAttribute.INT, 
                        RLSAttribute.LRC_PFN, 
                        12345),
                        "my-target-name-XYZ));

                try {
                    catalog.addAttributes(attributes);
                } catch(RLSException e) {
                    // handle exception
                }
            

In addtion to catalog queries by logical name, target name, or wildcards, the catalog may be search based on attribute values. Attribute searching supports the most common comparison operators (equality, less than, greater than, etc.), a similarity operator (like), and ranges (between).

                // Specify search parameters
                AttributeSearch asearch = new AttributeSearch(
                        "series",               // the name of the attribute
                        RLSAttribute.LRC_PFN,   // the object type
                        RLSAttribute.OPBTW,     // the comparison operation
                        new RLSAttribute(
                            "series",
                            RLSAttribute.LRC_PFN,
                            0),                 // the left value
                        new RLSAttribute( 
                            "series",
                            RLSAttribute.LRC_PFN,
                            99999),             // the right value
                        null);                  // optional offset/limit

                try {
                    Results results = catalog.query(asearch);
                    if (results.getRC() == RLSStatusCode.RLS_SUCCESS) {
                        List batch = results.getBatch();
                        Iterator i = batch.iterator();
                        while (i.hasNext()) {
                            // Returns RLSAttributeObject values
                            RLSAttributeObject aobj = (RLSAttributeObject) i.next();
                            if (aobj.rc != RLSStatusCode.RLS_SUCCESS)
                                continue;

                            // The search was on LRC_PFN objects therefore the 
                            // key is the target name. If the search was on
                            // LRC_LFN objects the key would be the logical
                            // name. The search returns the attributes and the
                            // object (logical or target) names that the
                            // attributes are associated with. It does not
                            // return the mapping.
                            String targetName = aobj.key;
                        }
                    }
                } catch (RLSException e) {
                    // handle exception
                }