Sun Java System Content Delivery Server Customization Guide

This chapter describes the Sun Java System Content Delivery Server Content Validation API. Use this API to create the content validation adapters that you need to validate and protect content that is submitted. Content validation adapters are used by the submission verifier workflow that is executed for content submitted to Content Delivery Server.

The Content Validation API consists of the following classes:

• ValidationAdapter - Abstract class that you extend to create your own content validation adapter. Implement your adapter to validate or modify the submitted content as needed.
• ValidationContent - Abstract class that you extend to create your own ValidationContent object. A ValidationContent object contains the information that identifies the content that was submitted.

The classes for the Content Validation API are in the com.sun.content.server.validation.adapter package. For additional information on these classes, see the HTML output of the Javadoc tool at $CDS_HOME/javadoc/validation/index.html.

---

5.1 General Process Flow

Each item of content that is submitted to Content Delivery Server is processed by a workflow defined in the $CDS_HOME/deployment/deployment-name/conf/SubmissionVerifierWorkflows.xml file. A workflow consists of a sequence of steps. In each step, the content validation adapter named in that step performs some type of processing on the content binary. For example, one step might provide obfuscation and another step might add code for digital rights management (DRM). See Section 14.3, “Creating a Workflow,” in the Sun Java System Content Delivery Server Integration and Configuration Guide for information on creating content validation workflows.

For each step in the workflow, Content Delivery Server calls the content validation adapter that is specified for that step and passes it a ValidationContent object and a Properties object. The ValidationContent object contains the metadata and content binary for the content submitted. The Properties object contains the arguments defined in the workflow for that step.

For the first step in the workflow, Content Delivery Server creates an initial ValidationContent object. For each subsequent step, the ValidationContent object that was returned by the previous step is passed to the content validation adapter for the next step.

---

5.2 ValidationAdapter Class

The ValidationAdapter class processes the metadata and content binary and performs any transformation that is needed. This section describes the methods that you need to implement.

5.2.1 execute Method

public abstract ValidationContent execute(ValidationContent content, java.util.Properties properties) throws java.lang.Exception

The execute method is called by Content Delivery Server when a step in the workflow is executed. The arguments for this method ar the ValidationContent object from the previous step and the arguments specified in the workflow step. You must know what type of ValidationContent object is created in the previous step in the workflow. For example, if your adapter is used in the first step in the workflow, it must be prepared to receive an InitialValidationContent object from Content Delivery Server.

In your implementation of this method, you must handle the properties that are passed and create a ValidationContent object to return. Process the metadata and content binary as needed. For example, to obfuscate the code, call the obfuscator that you want to use to transform the content binary and return the new binary in the ValidationContent object. You must know what type of ValidationContent object is expected in the next step in the workflow and generate that type of object. For example, if the next step in the workflow expects to receive a custom ValidationObject, this method must generate that custom ValidationObject.

If your adapter requires information that might change or that you do not want to hard code, create a property file for these values. The adapter can then access the information from the file through the Properties object that is passed as a parameter. For example, if your adapter obfuscates the code, you might need a property that identifies the location of the obfuscator on the system on which the adapter is running. The property file that you create must be placed in the $CDS_HOME/deployment/deployment-name/conf directory. You must also set the property file name for your adapter in the $CDS_HOME/deployment/deployment-name/conf/SubmissionVerifierAdapters.xml file as described in Section 5.4, Using the Content Validation API.

5.2.2 returns Method

public static java.lang.Class returns(java.lang.Class inputType) throws java.lang.Exception

The returns method is called by Content Delivery Server to verify that the adapter can handle the type of ValidationContent object to be passed. This method must return the same type of object that the execute method returns. For example, if the execute method returns a custom ValidationContent object, the returns method must return the same type of custom ValidationContent object.

See Section 5.5, Sample Content Validation Adapter for a sample implementation of this method.

---

5.3 ValidationContent Class

The ValidationContent class is an abstract class that you can extend to create a customized validation adapter. This class contains the metadata and binary for the content. If an adapter in a following step in the workflow needs additional information for the content, add that information to the class that you extend from this class.

---

5.4 Using the Content Validation API

The classes for the Content Validation API are available in the cdsapi.jar file. This file must be in your classpath when you compile your adapter. For convenience, a copy of all Content Delivery Server JAR files are available in the $CDS_HOME/dist/cds/staging/jar directory. Use this staging area in your classpath when compiling the adapter that you create.

Making your adapter available to Content Delivery Server depends on the application server you are using and whether you have already deployed. To make your adapter available, follow these steps:

1. Create a JAR file for your adapter.

2. For all application servers, place the JAR file in the $CDS_HOME/dist/cds/lib/external directory.

The adapter is now included in all future deployments.

3. If you have existing deployments that need to use the adapter, place the JAR file in the $CDS_HOME/deployment/deployment-name/lib/external directory for each deployment.

If you are using WebLogic Server, the classpath is handled for you.

If you are using Sun Java System Application Server, update the classpath for each deployment:

a. Back up the $CDS_HOME/deployment/deployment-name/sun/domains/cdsdomain/config/domain.xml file before editing it so you can recover from any errors that might be introduced during editing.

b. Edit domain.xml and modify the java-config element to add the absolute path for your JAR file to the classpath-suffix attribute.

c. Save your changes.

4. Edit the SubmissionVerifierAdapters.xml file in the $CDS_HOME/deployment/deployment-name/conf directory:

a. Add a statement for the adapter that you created.

For example, if you created an adapter named MyValidationAdapter that requires a property file named validation.properties, add the following statement to the file:

<adapter id="MyValidationAdapter" name="sample.package.MyValidationAdapter"
propertyfile="validation.properties"/>

b. Save your changes.

5. Edit the SubmissionVerifierWorkflows.xml file in the $CDS_HOME/deployment/deployment-name/conf directory:

a. Add a step to the appropriate workflow to execute the adapter that you created.

For the value of the adapter attribute for the step element, specify the value provided for the id attribute of the adapter element that you added to the SubmissionVerifierAdapters.xml file in Step a. See Section 14.3, “Creating a Workflow,” in the Sun Java System Content Delivery Server Integration and Configuration Guide for information on creating a workflow.

b. Save your changes.

6. Restart any existing deployment to make it aware of the new JAR file.

---

5.5 Sample Content Validation Adapter

The following code example is a sample of how the ValidationAdapter class can be extended to implement your own validation adapter.

import com.sun.content.server.validation.adapter.*;
import java.io.FileOutputStream;
import java.util.Properties;
 
public class ExportToFileValidationAdapter
extends ValidationAdapter
{
  public ValidationContent execute(
    ValidationContent content, Properties properties)
  throws Exception
  {
    // Export if the filename is specified
    String outFilename =
      properties.getProperty("ExportToFile.FileName");
    if (outFilename != null)
    {
      FileOutputStream fileOutStream = null;
      try
      {
        // get the first byte[] in the map
        // ignore the rest for this sample 
        byte[] bytes = (byte[])
          content.getMimeBytesMap().values().iterator().next();
 
        // Write the byte[] to the output file.
        fileOutStream = new FileOutputStream(outFilename);
        fileOutStream.write(bytes);
        fileOutStream.flush();
        fileOutStream.close();
        fileOutStream = null;
      }
      finally
      {
        if (fileOutStream != null)
        {
          fileOutStream.flush();
          fileOutStream.close();
        }
      }
    }
 
    content.setStatus(ValidationContent.VALID);
 
    return content;
  }
 
  public static Class returns(Class inputType) throws Exception
  {
    if (!ValidationContent.class.isAssignableFrom(inputType))
      throw new Exception("Wrong input type to adapter.");
    return ValidationContent.class;
  }
}

Sun Java System Content Delivery Server Customization Guide

820-1941-10

Copyright © 2008, Sun Microsystems, Inc. All Rights Reserved.