Sun Java System Content Delivery Server Integration and Configuration Guide

Content submitted to Sun Java System Content Delivery Server goes through a validation process that is managed by the submission verifier workflows. A workflow typically includes steps to validate the content using content validation adapters. The workflow that is executed is determined by the criteria that you specify. Content that does not require special processing must be processed by the default workflow.

This chapter includes the following topics:

• Content Validation Adapters
• Workflows Provided
• Creating a Workflow
• Specifying Workflow Criteria

---

14.1 Content Validation Adapters

A content validation adapter is used in a submission verifier workflow to process the content that is submitted to Content Delivery Server. Any preprocessing that is required before the content is accepted can be handled by an adapter. For example, adapters can be used to verify that the content meets the guidelines established by your enterprise, add code for digital rights management (DRM), or obfuscate the code.

14.1.1 Adapters Provided

Each step in a workflow must include the name of the content validation adapter to be run for that step. The following table describes the adapters that are provided with Content Delivery Server.

14.1.2 Writing an Adapter

If none of the adapters provided meets your needs, you can create your own adapter using the Content Validation API. See the Sun Java System Content Delivery Server Customization Guide for information on the Content Validation API.

If the adapter that you write needs values that cannot be known at the time the adapter is written, create a property file for the adapter. For example, if the adapter needs to know the location of a utility that it uses, create a property file that contains a property for the location. Set the location property to point to the directory that contains the utility on the system on which the adapter runs. Write the adapter to reference the location property when the location of the utility is needed. The property file that you create must be placed in the $CDS_HOME/deployment/deployment-name/conf directory.

14.1.3 Registering a Content Validation Adapter

To register an adapter that you wrote, add a statement in the $CDS_HOME/deployment/deployment-name/conf/SubmissionVerifierAdapters.xml file. If the adapter requires values in a property file, specify the name of the file in the property-file attribute. The property file must be in the $CDS_HOME/deployment/deployment-name/conf directory.

The following code example shows the registration statements for a sample adapter named MyValidationAdapter that requires a property file named MyValidation.properties.

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

---

14.2 Workflows Provided

Workflows provided with Content Delivery Server are defined in the $CDS_HOME/deployment/deployment-name/conf/SubmissionVerifierWorkflows.xml file. Predefined workflows are available for the following types of content:

• Java applications
• iAppli applications that use the DoJa library
• Copyrighted externally hosted content
• All other content (default workflow)

You can use these workflows as provided, or modify them as needed. For example, if you do not want to perform an action provided in a workflow, such as API filtering, comment out the step for that action. To add steps to a workflow or create a new workflow, see Section 14.3, Creating a Workflow. If you want to execute a workflow for content other than that specified by the default criteria, change the criteria as described in Section 14.4, Specifying Workflow Criteria.

14.2.1 Workflow for Java Applications

Content Delivery Server supports Java applications that use the MIDP 1.0 or MIDP 2.0 library. A default workflow is provided for use with most Java applications. A workflow for signing Java applications not protected by a CDS DRM agent is also provided.

14.2.1.1 Default Workflow for Java Applications

The default workflow for Java applications performs API filtering, stores the content, and checks if the content is to be published automatically. If no DRM method is used to protect the content, the content is stored in its original form. If a CDS DRM agent is used to protect the content, the workflow instruments the MIDlet. For MIDP 2.0 MIDlets, the workflow also adds any needed permissions to the MIDlet-Permissions and MIDlet-Permissions-Opt attributes and signs the MIDlet.

Disable an action by commenting out the associated step. For example, if you do not want to perform API filtering, comment out step 2 of the workflow.

Do not comment out the step named AddingDerivedEdition. This step stores the version of the content that subscribers download and is required.

To sign applications, a keystore file that contains the private key and trusted certificate for your installation is required. Use the keytool utility provided with the JDK software to create this file. You must specify RSA for the keyalg parameter. See the JDK software documentation for information.

If a CDS DRM agent is used to protect the content, you must set the following properties in the $CDS_HOME/deployment/deployment-name/conf/cdsdrmagent.properties file:

• MIDletSigning.MIDP20.enabled. Set this property to true to sign MIDP 2.0 MIDlets. Set to false if you do not want to sign the MIDlets.
• MIDletSigning.KeyStoreFilePath. Set this property to the fully qualified path name and file name of the keystore file.
• MIDletSigning.KeyStorePassword. Set this property to the password used to access the keystore.
• MIDletSigning.KeyAlias. Set this property to the alias of the private key that you want to use to sign the MIDlet.
• MIDletSigning.KeyPassword. Set this property to the password associated with the private key named by the key alias.

14.2.1.2 Workflow for Signing Java Applications

If you do not use a CDS DRM agent to protect content and have a need to sign MIDP 2.0 MIDlets, an alternate version of the workflow for Java applications is provided. To use this workflow, you must create criteria as described in Section 14.4, Specifying Workflow Criteria that identifies the content that you want processed by this wokflow. The criteria for this workflow must precede the criteria for the default workflow for Java applications in the file.

The workflow for signed applications requires a keystore file that contains the private key and trusted certificate for your installation. Use the keytool utility provided with the JDK software to create this file. You must specify RSA for the keyalg parameter. See the JDK software documentation for information.

Edit the Signed Java Application Workflow in the SubmissionVerifierWorkflows.xml file and provide the fully qualified path and file name of the keystore file as the value for the MIDletSigning.KeyStoreFilePath in step 3 of the workflow. You must also provide values for the MIDletSigning.KeyStorePassword, MIDletSigning.KeyAlias, and MIDletSigning.KeyPassword properties. See Section 14.2.1.1, Default Workflow for Java Applications for information on these properties.

14.2.2 Workflow for iAppli Applications

Content Delivery Server supports iAppli applications that use the DoJa library. The default workflow for iAppli applications performs API filtering, stores the content in its original form, and checks if the content is to be published automatically.

Disable an action by commenting out the associated step. Do not comment out the step named AddingDerivedEdition. This step stores the version of the content that subscribers download and is required.

14.2.3 Workflow for Externally Hosted Copyrighted Content

The workflow for externally hosted copyrighted content identifies content that must not be cached by Content Delivery Server because of copyright restrictions. This workflow creates an entry in the catalog for the content, ensures that only the metadata is stored for the content, and checks if the content is to be published automatically.

Disable an action by commenting out the associated step. The first two steps in this workflow are required. Do not comment out the step named AddingDerivedEdition or the step named PreventingCopies.

If you want Content Delivery Server to accept this type of content, remove the beginning and ending comment statements from the criteria named isCopyrighted that specifies execution of the workflow named Copyrighted External Content Workflow.

Any content except for Java applications and iAppli applications can be marked as copyrighted. To specify the content for which this workflow is executed, set the criteria as described in Section 14.4, Specifying Workflow Criteria.

14.2.4 Default Workflow

The default workflow is executed for all content that doesn’t match the criteria for any other workflow. The default workflow stores the content in its original form and checks if the content is to be published automatically.

Do not comment out the step named AddingDerivedEdition. This step stores the version of the content that subscribers download and is required.

---

14.3 Creating a Workflow

A submission verifier workflow describes the steps taken to validate and protect content submitted to Content Delivery Server. The following code example shows the workflow for externally hosted copyrighted content.

<workflow id="4" name="Copyrighted External Content Workflow" 
          activation="manual">
  <desc>
    This workflow is used to ensure copyrighted external content is not stored
  </desc>
  <step-list>
    <step id="1" name="AddingDerivedEdition" adapter="AddDerivedEditionAdapter">
      <desc>
        This step adds a downloadable edition derived from the original
      </desc>
      <argument-list>
        <argument name="AddDerivedEdition.EditionNameSuffix"
                  kind="indirect" value="editionnamesuffix""/>
        <argument name="AddDerivedEdition.StoreOriginalBytes"
                  kind="direct" value="true"/>
      </argument-list>
    </step>
    <step id="2" name="PreventingCopies" adapter="CopyrightAdapter">
      <desc>
        This step removes any locally stored copies of the content
      </desc>
    </step>
    <step id="3" name="AutoPublish" adapter="AutoPublishAdapter"/>
  </step-list>
</workflow>

Each workflow that you define requires the following items:

• A unique workflow ID.
• A list of steps. Within the list, each step must have a unique ID and name and specify the name of the adapter to be executed.
• A step that executes AddDerivedEditionAdapter. This step stores the version of the content that a subscriber downloads. Every workflow that executes this adapter must contain at least one step. If your workflow modifies the content to create the edition that is downloaded, AddDerivedEditionAdapter must be executed after the steps that perform the modifications and the argument AddDerivedEdition.StoreOriginalBytes must be set to false. Otherwise, the modifications are lost.

If your workflow creates more than one edition, the edition delivered to the subscriber depends on the capabilities of the device. If more than one edition matches the device, the last edition created that matches is the one delivered. For example, if steps 2, 5, and 7 in your workflow create unique editions of the content and the device is capable of running the editions created in steps 2 and 7, the edition created in step 7 is delivered.

• An argument list. If the adapter used in a step requires arguments, the step must include an argument list.

To automatically publish content based on rules defined in the $CDS_HOME/deployment/deployment-name/conf/AutoPublishRules.properties file, include a step that executes AutoPublishAdapter. See Section 1.7, Setting Up Automatic Publishing for information on setting up the rules.

Add your workflow to the $CDS_HOME/deployment/deployment-name/conf/SubmissionVerifierWorkflows.xml file. See Section 14.4, Specifying Workflow Criteria to specify the criteria for which your workflow is executed.

14.3.1 Using the Add Capability Adapter

The adapter AddCapabilityAdapter can be used to add required device capabilities to content during the verification process. For example, you can use this adapter to add the bit rate that a device is capable of handling for MP3 files.

The following code sample shows a workflow step that uses this adapter.

<step id="100" name="Cap" adapter="AddCapabilityAdapter">
  <desc>
    Add audio/mp3-24kbps to ccppaccept capability when
      the edition name contains "-24kbps"
  </desc>
  <argument-list>
    <argument name="AddCapability.EditionNameRegEx" kind="direct" 
        value="-24kbps"/>
    <argument name="AddCapability.CapabilityName" kind="direct"
        value="ccppaccept"/>
    <argument name="AddCapability.CapabilityValue" kind="direct"
        value="audio/mp3-24kbps"/>
   </argument-list>
</step>

This step must appear before the AddDerivedEditionAdapter step so that the values from this step can be added to the derived edition. Otherwise, the values are never saved.

14.3.2 Using the External to Internal Adapter

The adapter ExternalToInternalAdapter can be used to convert externally hosted content that was submitted through the Content Aggregator Interface to local content.

The following code sample shows a workflow step that uses this adapter.

<step id="300" name="EtoI" adapter="ExternalToInternalAdapter">
  <desc>
    Convert external content to internal content when
    the edition name contains "-extint"
  </desc>
  <argument-list>
    <argument name="ExternalToInternal.EditionNameRegEx" kind="direct" 
      value="-extint"/>
  </argument-list>
</step>

This step must appear before the AddDerivedEditionAdapter step so that the conversion can be propagated to the derived edition. Otherwise, the values are never saved.

14.3.3 Using the Process OMA DRM Message Adapter

The adapter ProcessOmaDrmMessageAdapter can be used to accept content that is prewrapped with OMA DRM 1.0 protection and packaged in a DRM message. This adapter adds the MIME type of the protected content as a required device capability.

The following code sample shows a workflow step and criteria that use this adapter.

<workflow id="5" name="OMA DRM Message Parser" activation="manual">
  <desc>Parse submitted DRM Message and update appropriate content 
    capabilities depending on plain content wrapped inside DRM message</desc>
  <step-list>
    <step id="1" name="ProcessOMADRMMessage" 
      adapter="ProcessOmaDrmMessageAdapter">
          <desc>This step parses the DRM wrapped content</desc>
    </step>
    <step id="2" name="AddingDerivedEdition" 
        adapter="AddDerivedEditionAdapter">
    <desc>This step adds a downloadable edition derived from the original</desc>
      <argument-list>
        <argument name="AddDerivedEdition.EditionNameSuffix" 
            kind="indirect" value="editionnamesuffix"/>
        <argument name="AddDerivedEdition.StoreOriginalBytes" kind="direct" 
           value="true"/>
        </argument-list>
    </step>
  </step-list>
</workflow>
 
<criteria id="5" name="isDrmMessage">
  <desc>A sample validation workflow for a submitted OMA DRM Message</desc>
  <workflow-list>
    <workflow id="4">
      <argument-list>
       <argument name="editionnamesuffix" value="_OMADrmWrappedDownloadable"/>
      </argument-list>
    </workflow>
  </workflow-list>
  <criterion name="mime-type" value="application/vnd.oma.drm.message"/>
</criteria>

14.3.4 Using the Set Edition Weight Adapter

The adapter SetEditionWeightAdapter can be used to specify the edition weight for an edition of content. Edition weight can be used during capability matching to determine which edition is delivered to a device that matches multiple editions of content. If multiple editions match a device, the edition with the highest edition weight is delivered.

The following code sample shows a workflow step that uses this adapter.

<step id="200" name="Weight" adapter="SetEditionWeightAdapter">
  <desc>
    Set the edition weight to 100 when
    the edition name contains "-24kbps"
  </desc>
  <argument-list>
    <argument name="SetEditionWeight.EditionNameRegEx" kind="direct"
      value="-24kbps"/>
    <argument name="SetEditionWeight.WeightValue" kind="direct" value="100"/>
  </argument-list>
</step>

This step must appear before the AddDerivedEditionAdapter step so that the values from this step can be added to the derived edition. Otherwise, the values are never saved.

---

14.4 Specifying Workflow Criteria

Each workflow must have at least one set of criteria that identifies the content for which the workflow is executed. This criteria is defined with the workflows in the $CDS_HOME/deployment/deployment-name/conf/SubmissionVerifierWorkflows.xml file.

Only one workflow is executed for each item of content. The workflow executed is determined by the first set of criteria that the content matches, so the order of criteria is important. If more than one criterion is specified in a set of criteria, all criterion must be met for the content to be considered a match.

CODE EXAMPLE 14-7 shows sample criteria for the workflow for externally hosted copyrighted content.

<criteria id="3" name="isCopyrighted">
  <desc>
    Sample criteria for copyrighted external content.
    Note: only external content can be copyrighted.
    Note: the only DRM supported for copyrighted content is None.
    Note: criterion names and values are case insensitive.
    Note: for location-type, specify e for external or i for
     internal.
  </desc>
  <workflow-list>
    <workflow id="4">
      <argument-list>
        <argument name=”editionnamesuffix value=”_Copyrighted”/>
      </argument-list>
    </workflow>
  </workflow-list>
  <criterion name="location-type" value="e"/>
  <criterion name="content-type" value="ringtone"/>
  <criterion name="mime-type" value="audio/mp3"/>
  <criterion name="developer-plan" value="copyrightplan"/>
  <criterion name="developer" value="composer"/>
</criteria>

Edit the criterion for an existing set of criteria or create additional sets of criteria to identify the content that you want to be processed by a workflow. For each new set of criteria:

• Provide a unique value for the criteria id attribute.
• For the workflow id attribute, specify the ID of the workflow that you want to assign. For example, for the copyrighted external content workflow, this value is 4.
• If the specified workflow requires input values, include an argument list within the workflow element and provide the argument names and values.
• Order the sets of criteria within the file with the most restrictive set first. As soon as the content matches a set of criteria, no other criteria are checked. The last set of criteria must specify the default workflow and must not contain any criteria.

Use any combination of the following attributes as the criterion in a set of criteria. The workflow is executed if content matches all items specified.

• location-type. Specify e for externally hosted content, i for locally hosted content.
• content-type. Specify a content type that is supported by Content Delivery Server.
• mime-type. Specify a MIME type that is supported by Content Delivery Server.
• developer-plan. Specify the name of a Developer Plan.
• developer. Specify the user name of a developer.
• MicroEdition-Configuration. Specify the MicroEdition Configuration version for the MIDlet, for example, CLDC-1.0.
• MicroEdition-Profile. Specify the MicroEdition Profile version for the MIDlet, for example, MIDP-1.0.
• ConfigurationVer. Specify the Configuration Version for the iAppli application, for example, CLDC-1.0.
• ProfileVer. Specify the Profile Version for the iAppli application, for example, DOJA-1.0.

Sun Java System Content Delivery Server Integration and Configuration Guide

820-1944-10

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