XMC Cat Command Line Client Code Examples

From D2I Wiki
Jump to: navigation, search

Contents

XMC Cat Client

When you build XMC Cat, a client jar is created which can be used to create a stub for accessing the XMC Cat catalog and running any of the operations exposed in the WSDL (of course you can also create your own client from the WSDL if you are not using java).

The jars you will need from the build are: 

  xmccat-client-1.x.x.jar (xmccat-client)
  xmccat-types-metadata-1.x.x.jar (xmccat-types-metadata)

These jars will be in the target folders of the corresponding sub-projects (in parenthesis above) after you run the XMC Cat build process. The client programs that deal directly with metadata will also require the jar for your metadata schema. For example, for the LEAD metadata schema you will need the lead-metadata-1.X.X.jar, and for the FGDC metadata schema you would need the d2i-fgdc-schema-1.0.0.jar. Both of these are available on the downloads page.

In addition to the above files, so the client can connect to Axis2, you will need all of the jars in the lib folder from the Axis2 binary distribution on your classpath. The Axis2 binary distribution can be downloaded from this page at the Axis2 website.

Example Client Programs

Following is some example code for using the operations exposed by the XMC Cat catalog service. All of these sample programs use the Java namespace "edu.indiana.dtoi.test.xmccat." The output for each program includes the XML for the operation that is sent to the XMC Cat metadata catalog and then the response received back from the catalog.

In the programs for adding metadata describing data objects (e.g., experiments or files), as well as the program for adding properties to an existing object, snippets of XML based on the LEAD Schema are provided as files. As a web service, the operations in XMC Cat use parameters defined in the XMC Cat types schema which is then imported into the WSDL for the web service. These operations parameters will contain instances of the metadata based on the schema for which the catalog is implemented. These example programs are based on the LEAD Metadata Schema (LMS), so the snippets of XML used to run the examples are based on the LMS.

In an actual client program accessing the XMC Cat metadata catalog, code would be written that creates the metadata using the XML bean for the domain schema (such as the LMS for these examples). To allow different sets of parameters to be specified for these sample programs, the parameters are loaded from XML files specified on the command line. Where these are needed for any of the example programs below, sample XML based on the LEAD metadata schema are provided. These can be used as is or modified as you desire (just be sure they are still schema valid if you modify them).

Similarly, in the sample programs for the query operations, the XML for the "target" or "context" for a query is loaded into the program from an XML file at the command line and then XML Beans is used to parse that file to build the query. In these sample programs this is done so we can easily try out different queries by creating snippets of XML. However, if you base your own client programs on these examples, we would recommend building the target and context for a query using the XML Bean class for that operation instead of creating XML externally and then loading it into an XML Bean by parsing it.

If these examples are run from the command line or from within an IDE such as Eclipse, including only -help as a parameter will provide brief instructions as to the parameters that can be specified for that program. All of the parameters are specified by preceding them with a flag (e.g., -h for the host at on which the XMC Cat metadata catalog is deployed). This allows the parameters to be specified in any order. If you are using Eclipse or a similar IDE, multiple alternatives can be setup in the parameters for running the test programs by just setting the unused flags to invalid options (e.g., -hx for the host parameter).

These tests all require the XMC Cat client that is built as part of the XMC Cat build process and some additional jars as described above. Since these examples are based on the LMS, you will need the XML Bean for the LEAD Metadata Schema. The first program listed below (TesterBase) is used to create the stub to connect to XMC Cat and is extended by all of the other sample programs.

Each of the following sample files is posted separately below as a .java source code file.

Using the Samples With a Secure XMC Cat

On the XMC Cat installation page there are instructions for configuring the XMC Cat server to use transport level security based on Apache Rampart. If your XMC Cat is implemented as a secure XMC Cat, then include the flag -s (with no additional parameter) to create a stub to a secure XMC Cat. To enable the TesterBase class to create a secure client stub, there are three additional steps:

  • Include the PWCBHandler class file below.
  • All of the files in the lib folder of Apache Rampart standard binary distribution need to be included on the classpath. The Apache Rampart standard binary distribution can be downloaded from here. The samples below were tested using Apache Ramprt version 1.5.1.
  • The sampleClientRepo.tar.gz file below should be downloaded and unzipped to a location accessible from your code. When untarred, this will contain a folder named client-repo that contains two Apache Rampart modules for Axis2, the security policy file for the transport security, and an Axis2 configuration file. Set an environment variable named "clientRepoPath" that is the full path to the client-repo directory.

Example XMC Cat Client Programs Based on the LMS:

TesterBase

This is the abstract base file all of the test programs extend. This was added so the code for creating the XMC Cat client stub and adding the user's DN as a header could be reused for all of the tests.

XMC Cat Status

checkStatus operation which provides some basic stats about current status of the XMC Cat metadata catalog. Run with -help to see the options for this operation.

Add Object

createObject operation. Run with -help to see the options for this insert. The schema-valid document is passed as a file. If you need data, this is a file that uses the LEAD Metadata Schema (LMS) to describe a meteorological data product generated by Unidata and used in the LEAD portal. If you have metadata in your XMC Cat installation already, then you can run the context query or the query by ID and use the metadata returned (using the FULL_SCHEMA content filter). A replacement GUID can be passed as a parameter - just make sure it is unique. If you want the routine to generate a new global ID for you, pass "new" as the replacement GUID.

Adding Objects with Faceted Capabilities

If you have XMC Cat installed with the ability to ingest data and shred it into facetted elements for the feaceted query, then use this metadata file as the metadata file, which is a slightly modified version of adasdata.xml listed above. At this point, you should already have facet definitions and facet category definitions loaded into the database. You can use this script to insert facet and category definitions that work with this sample data.

Add Concept

addProperty operation. Adds metadata concepts to an already cataloged object. Run with -help to see the options for this operation. This sample program takes text files with the XML for the concepts to be added. The XML contained in each file should be the full XML for the catalogProperty element from the XMC Cat types schema. Here is a sample file for adding a theme keyword concept based on the LEAD Metadata Schema and this file adds the concept for a parameter block from a namelist configuration file used in LEAD.

Update Concept

updateProperty operation. This operation is used to update an existing concept in the metadata describing an object. This sample program takes an XML file containing the updated concept as a parameter (the catalogPropertyUpdate element in the XMC Cat schema). This sample theme update file can be used to update an existing theme concept based on the LEAD Metadata Schema. The theme contained in this sample is not intended to be realistic - just easy to locate in the updated metadata.

Add User

createUser operation. This defines a new user in the catalog. This sample program takes a file that contains the XML defining a new user. This is the catalogUser element from the types schema. This example user file can be used for the file parameter. So that the file can be reused without editing, the test program takes additional parameters for a new user DN and/or user name that should be substituted for the user in the file. Each user must have a unique DN.

Query By Object ID

objectIdQuery operation. Run with -help to see the options for this query based on the object's global ID. This example will retrieve the metadata for an object based on that object's global ID. This example has options for some of the different filters available for the query result, Only one hierarchy and one content filter can be applied to a single query. If multiple content filters are entered, the precedence is (1) concept filter, (2) element filter, (3) FULL_SCHEMA or ID_ONLY. The default is ID_ONLY. The options available in this example include:
1. Hierarchy: TARGET (the object itself)
2. Hierarchy: SUBTREE (the object itself and all of its direct and indirect children)
3. Content: FULL_SCHEMA (the full metadata for each object returned)
4. Content: ID_ONLY (Just the global ID of each object is returned - this really only makes sense if you are using the SUBTREE hierarchy filter)
5. Content: Concept Filter. This is passed as an XML file for the sample program and defines those concepts from the schema that should be returned in the result. Example file that retrieves all of the workflow notification concepts.
6. Content: Element Filter. This is passed as an XML file for the sample program and defines those leaf elements in the metadata schema that should be returned in the result. This is essentially a way to get back simple name/value pairs. Example file that retrieves the title and any theme keywords for each object.

Context Query

query operation. Run with -help to see the options for this query. For this example the target for the query is passed as a file containing XML representing the target element from the XMC Cat types schema. This sample target file is an example which looks for files created within a specified temporal range and where the title of the file contains "NAM" (a type of meteorological data).

This is another example that builds on that first example but adds an "OR" condition that matches the files retrieved in the prior target, plus files where the center latitude is north of 25 and the grid spacing for the forecast is less than 10km.

The first two examples just specified the target of the query, but you can also specify the context for the target. An example of such a context query is "get me all files where the file name (title) starts with "wrfout" and the experiment it belongs to is within certain temporal and spatial bounds". These are the target and context files for that example.

As is the case with the other sample programs, the query would generally be built using the XML Bean for the XMC Cat types schema and not loaded from a text file. The same filter options discussed above for the Query By ID with regards to the hierarchy and content of the metadata are also available in this sample program.

Concept Definitions Query

queryPropertyDefinitions operation. This query returns all of the concepts defined in the catalog (based on the domain schema implemented). The concepts are grouped into domain categories specified in the catalog. The sub-concepts and elements are also included in the response for each concept. This query is used to dynamically build the query interface in the XMC Cat GUI interface so the query interface can be automatically tailored to the domain the catalog is serving. Results can be returned directly in the response or streamed back.

All Workspace Query with facet retrieval

AllWorkSpaceQuery operation. This query is used to get all of the metadata describing objects in a user's workspace. By default it gets only global ID for each object although the FULL_SCHEMA content filter can be used. The results of this query can be returned directly in the response or streamed back. Additionally there is a filter called facet response type, which can be set to either FACET_COUNTS or ONLY_FACETS. Specifying FACET_COUNTS will return the metadata that would otherwise be returned by the AllWorkSpaceQuery operation PLUS the facets and their respective counts. Alternately, the ONLY_FACETS option will return only the facets and their category counts and suppress the other metadata.

Example Client Programs Prior to the Security Option

Click the above link to reach the page with versions prior to the addition of security.

Retrieved from "http://d2i.indiana.edu/leadwiki/index.php?title=XMC_Cat_Command_Line_Client_Code_Examples&oldid=3014"
Personal tools