JET RESTful Resource pattern input file and the Java class it generates

Format of the pattern input file

Pattern input files provide the required information to the JET RESTful Resource pattern using the following format:

<rest componentName="component_name" packageNamePrefix="package_name_prefix">
	<noun name="noun_name" pluralNounName="plural_noun_name" 
         defaultAccessProfile="default_access_profile" defaultExpression="default_get_xpath_expression>
		<findBy expression="get_xpath_expression" name="findby_name"/>
	</noun>
</rest>

The following describes the variables in the pattern input file:

defaultExpression="/Catalog[@primary='false']"

Sample pattern input file

This example input file will generate the Java class required to get feed data from the Get Catalog service based on the unique ID of the catalog:

<rest componentName="Catalog" packageNamePrefix="com.ibm.commerce">
   <noun name="Catalog" pluralNounName="catalogs" defaultAccessProfile="IBM_Store_Details" defaultExpression="/Catalog[@primary='false']">
      <findBy expression="/Catalog[CatalogIdentifier[(UniqueID={0})]]" name="Id"/>
   </noun>
</rest>

Location of the pattern output file

The pattern generates a JAX-RS resource Java class at the following path, based on the variables you entered in the pattern input file:

package_name_prefix.component_name.rest.resources.noun_name.java

For example:

com.ibm.commerce.Catalog.rest.resources.Catalog.java

The following describes key snippets from the Java class file generated using the previous pattern input file example:

Sample snippet 1: JAX-RS URI to resource mapping

This snippet is near the top of the class file. The @Path annotation defines the URIs that this class handles. The annotation is generated based on the noun name in the pattern input file. In this example, the Catalog class, or resource, will handle all URIs in the form */stores/storeId/catalogs.

/**
 * This class converts RESTful Catalog requests into WebSphere
 * Commerce Catalog requests and returns data in either XML, JSON, or
 * Atom feed format.
 */
@Path("stores/{storeId}/catalogs")
@Encoded
public class Catalog {
…

Sample snippet 2: JAX-RS URI to method mapping

• Determine the requested response formats based on the responseFormat query parameters and the HTTP Accept header.
• Call the findByName helper method to perform the WebSphere Commerce service request.
• Return the response.

The @Path annotation defines the URIs that this method handles. This value is appended to the path defined for the class and is generated based on the findby_name value specified in the pattern input. In this example, this method handles all URIs in the form */stores/storeId/catalogs/findby_name.

/**
	 * This method performs a GetCatalog by id request.
	 * 
	 * @param id the Catalog id.
	 * @param storeId the store Id.
	 * @param accessProfile the access profile of the Get request.
	 * @param responseFormat the response format (xml, json, or atom).
	 * @return The Catalog noun in the specified format.
	 * @throws WebApplicationException 
	 * @throws IOException
	 * @throws CatalogException
	 */
	@GET
	@Produces( { "application/atom+xml", "application/json", "application/xml" })
	@Path("{id}")
	public Response findById(
	        @PathParam("id") String id,
	        @PathParam("storeId") String storeId,
	        @QueryParam(value = "accessProfile") String accessProfile,
	        @QueryParam(value = "responseFormat") String responseFormat
	        ) throws WebApplicationException, IOException, CatalogException {
	
	    final String METHODNAME = "findById(String, String, String, String, String, String)";
	
	    if (com.ibm.commerce.foundation.common.util.logging.LoggingHelper
	            .isEntryExitTraceEnabled(LOGGER)) {
	        LOGGER.entering(CLASSNAME, METHODNAME);
	    }
	    	  	
	    Response result = null;
	    Object[] params = { id };
	    String expression = MessageFormat.format(FIND_BY_ID_XPATH, params);
	
	    // Perform the service request and return the response in the appropriate format.
	    result = getCatalog(expression, accessProfile, responseFormat);
	    	
	    if (com.ibm.commerce.foundation.common.util.logging.LoggingHelper
	            .isEntryExitTraceEnabled(LOGGER)) {
	        LOGGER.exiting(CLASSNAME, METHODNAME);
	    }
	
	    return result;
	
	}

Sample snippet 3: Find by name helper method

• Create a GET service request for the noun using the GET XPath expression defined in the pattern input file.
• Use the JAX-RS runtime to convert the response into Atom format.

   /**
	 * This method performs a <code>GetCatalog</code> service request.
	 * 
	 * @param expression the XPath expression.
	 * @param accessProfile the access profile of the get expression.
	 * @param responseFormat the response format.
	 * @return the Catalog noun.
	 * @throws CatalogException the exception representing the error of the
	 *             <code>GetCatalog<code> request.
	 * @throws WebApplicationException 
	 * @throws IOException
	 */
	protected Response getCatalog(String expression, String accessProfile, String responseFormat)
			throws CatalogException, WebApplicationException, IOException {

		final String METHODNAME = "getCatalog(String, String, String)";

		if (com.ibm.commerce.foundation.common.util.logging.LoggingHelper
				.isEntryExitTraceEnabled(LOGGER)) {
			LOGGER.entering(CLASSNAME, METHODNAME);
		}
		
		 // Get the response format, either from the Http header or URL, the URL takes precedence.
	    MediaType format = StoreConfigurationHelper.getResponseFormat(responseFormat, headers);
		
		if (accessProfile == null) {
	    	accessProfile = DEFAULT_ACCESS_PROFILE;
	    }
						
		// Build the Get request.
		SelectionCriteriaHelper selectionCriteria = buildExpression(expression, accessProfile);
		GetType getVerb = buildGetVerb(selectionCriteria.getSelectionCriteriaExpression());
						
		// Perform the service request.
		CatalogFacadeClient client = new CatalogFacadeClient(businessContext, null);
		DataObject dataArea = (DataObject) client.getCatalog(getVerb);
																
		// For XML or JSON, the JAX-RS runtime will resolve the appropriate provider.
		// For Atom, the feed is directly populated.
		Response result = null;
		if (MediaType.APPLICATION_ATOM_XML_TYPE.isCompatible(format)) {
			AtomFeedSDOProvider provider = new AtomFeedSDOProvider();
			AtomFeed feed = provider.writeTo(dataArea, businessContext, uri, context);
			result = Response.ok(feed).type(MediaType.APPLICATION_ATOM_XML).build();
		} else {
			result = Response.ok(dataArea).type(format).build();
		}	
		
		if (com.ibm.commerce.foundation.common.util.logging.LoggingHelper
				.isEntryExitTraceEnabled(LOGGER)) {
			LOGGER.exiting(CLASSNAME, METHODNAME);
		}

		return result;
	}