XPath Query Search

From Governance Registry 4.5.0, resource search is enhanced by providing support to XPath Query search. With this enhancement users would be able to search resources using a XPath query based on resource names, locations or by defining media type. And the search can be further enhanced by providing other search criteria s as well. 

1. The XPath Query that will be used for searching can be in any of the given following format. The queries should be preceded by either '/' or '//' according to the search format. And rest of the expressions should be separated by forward slashes '/'. 
   
   
   1. /<ANY_RESOURCE_OR_COLLECTION_NAME>/...
   2. //<ANY_RESOURCE_OR_COLLECTION_NAME>/...
   3. //<HUMAN_READABLE_NAME>
   4. //<HUMAN_READABLE_NAME>[<SEARCH CRITERIA>]
   5. //<HUMAN_READABLE_NAME>/<ASSOCIATION_NAME OR CHILD RESOURCE OR COLLECTION NAME>
   6. //<HUMAN_READABLE_NAME>[<SEARCH CRITERIA>]/<ASSOCIATION_NAME OR CHILD RESOURCE OR COLLECTION NAME>
   7. //<HUMAN_READABLE_NAME>[<SEARCH CRITERIA>]/<ASSOCIATION_NAME OR CHILD RESOURCE OR COLLECTION NAME>[<SEARCH CRITERIA>]
      
      
      

2. The XPath query search can be done by giving the registry path of a resource. The format  /<ANY_RESOURCE_OR_COLLECTION_NAME>/...  would return all the immediate child resources and collections of the selected resource or collection. The following query would give all the immediate child collections of _system.

   E.g. - /_system

    

3. A specific resource or collection under the root can be searched by just defining the name after '//' according to the format  //<ANY_RESOURCE_OR_COLLECTION_NAME>/...  (this may not work with root) . The query to search a resource called  foo  should be as given below.

   E.g. - //foo

    

4. The XPath search can be performed by being specific to a particular media type. The media type should be define in the query by a human readable name. Therefor prior executing such query the perticular human readable media type should be defined inside the $GREG_HOME/repository/conf/etc/mime.mappings. The way to exactly define a human readable media type is given in the page Configuration Files.
   
   

5. If it is needed to search and list out all the resources of a particular media type then according to the format //<HUMAN_READABLE_NAME> you can define only the human readable name of the media type after '//'. If service is the corresponding human readable name for service media type then all the services available in the registry would be resulted by providing the following query.

   E.g. -  //service

    

6. For more enhanced searching a search criteria can be defined along with the human readable name as given in the format //<HUMAN_READABLE_NAME>[<SEARCH CRITERIA>]  . A search criteria can be made using following information of a resource.
   
   1. resourcePath
   2. author
   3. updater
   4. associationType
   5. createdAfter
   6. createdBefore 
   7. updatedAfter
   8. updatedBefore
   9. commentWords
   10. tags
   11. propertyName
   12. propertyValue
   13. content
   14. mediaType

7. The given above information should be defined along with its values in the search criteria inside square brackets after the human readable name. In order to search services made by user admin the following query can be used. 

   E.g. - //service[@author='admin']

    

8. The facility of using operators is also available with XPath Query search. A user can have  "and"  and  "or"  in between predicates. Similarly you can have  "="  and  "!="  only for the information that accept negation ( author, updator, mediaType, created, updated ). You can also do  <, >, <=, >=,  for property values.  
   
   

1. If a service contains properties called "foo" and "bar" a search criteria can be defined to look up for services which has both the properties as given below.

   E.g. - //service[@propertyName='foo' and @propertyValue='bar']

    

2. And only for one of the properties as given below.

   E.g. - //service[@propertyName='foo' or @propertyValue='bar']

   
   

3. A range of values can also be defined for scenarios like search by the properties of a resource. In order to retrieve services which has the property "foo" with value less than or equal to 10 the query should be as follows.
   

   E.g. - //service[@foo <= 10]

    

4.  In scenarios like search a resource by tags, it may be necessary to define multiple values given as tags to do a search. Multiple values can be defined as given below.  

   E.g. - //service[@tags='axis,test']

    

9. It is also possible to define a registry location look up for resources or collections in that location. For an instance  //governance/trunk/  would list out all the resources and collections under the governance/trunk location.
   
   
10. Another advantage in searching using XPath Query is that the ability to get associations and dependencies of a resource. 
    

    1. In order to result  all the services which has usedBy type association the following query can be used.  

       E.g. - //service/usedBy

          

    2. And in order to result dependencies  of the services created by the user 'testUser' the following query can be used.  

       E.g. - //service[@author = 'testUser']/depends

       
       

11. Given below is a sample code segment which executes a XPath Query for search. 

public void searchFromXpathQuery(Registry registry) {
        try {
            //The XPath Query Expression
            String xpathExpression = "//service";
            
            //Creation of search parameters
            Map parameters = new HashMap();
            parameters.put("query", xpathExpression);
            parameters.put("mediaType", "application/vnd.wso2.xpath.query");

            Resource result = registry.executeQuery(null, parameters);
            String[] paths = (String[]) result.getContent();
            if(paths!=null){
                for (String path : paths) {
                    System.out.println("Results : " + path);
                }  
            }else{
                System.out.println("No search results available");
            }
            
        } catch (RegistryException e) {
            e.printStackTrace(); 
        }
    }