org.codehaus.enunciate.modules.java_client
Class JavaClientDeploymentModule

java.lang.Object
  extended by org.codehaus.enunciate.modules.BasicDeploymentModule
      extended by org.codehaus.enunciate.modules.FreemarkerDeploymentModule
          extended by org.codehaus.enunciate.modules.java_client.JavaClientDeploymentModule
All Implemented Interfaces:
EnunciateClasspathListener, EnunciateModelAware, DeploymentModule, FacetAware, ProjectExtensionModule

public class JavaClientDeploymentModule
extends FreemarkerDeploymentModule
implements ProjectExtensionModule, EnunciateClasspathListener, FacetAware

Java Client Module

The Java client module generates the client-side libraries that will access the Web service API. For SOAP endpoints, a client-side service interface will be generated that uses JAX-WS. For REST endpoints, the JAXB data model classes will be generated to access the XML endpoints. If there are any JSON endpoints, a set of data model classes will be generated that can be used in conjunction with the Jackson library to access them.

The order of the Java client module is 50, so as to allow the Java module to apply metadata to the endpoints before processing the client.

Steps

generate

The "generate" step is by far the most intensive and complex step in the execution of the Java client module. The "generate" step generates all source code for accessing the web service API.

compile

During the "compile" step, the Java client module compiles the code that was generated.

build

The "build" step assembles the classes that were assembled into a jar. If there are any JSON endpoints, the JSON client library will be assembled into a separate jar. It also creates a source jar for each library.

Configuration

The Java client module is configured by the "java-client" element under the "modules" element of the enunciate configuration file. It supports the following attributes:

The "package-conversions" element

The "package-conversions" subelement of the "java-client" element is used to map packages from the original API packages to different package names. This element supports an arbitrary number of "convert" child elements that are used to specify the conversions. These "convert" elements support the following attributes:

The "json-package-conversions" element

The "json-package-conversions" element has the same purpose and syntax as the "package-conversions" element above, but is instead applied to the JSON java client. By default, ths JSON conversions will be the same as the "package-conversions" with the "json" subpackage appended.

The "server-side-type" element

An arbitrary number of "server-side-type" elements are allowed as child elements of the "java-client" element. The "server-side-type" element can be used to specify a server-side type that is to be ported directly over to the client-side library (as opposed to generating the client-side type from the server-side type). This can be useful to provide more useful client-side capabilities, but requires that there be no package conversions for types and web faults.

The "server-side-type" element supports one attribute, "pattern" that defines an ant-style pattern of the type(s) that are to be included (using a '.' for separating the package name).

The "facets" element

The "facets" element is applicable to the Java Client module to configure which facets are to be included/excluded from the Java Client artifacts. For more information, see API Facets

Artifacts

The Java client module exports the following artifacts:

Author:
Ryan Heaton

Field Summary
 
Fields inherited from class org.codehaus.enunciate.modules.BasicDeploymentModule
enunciate
 
Constructor Summary
JavaClientDeploymentModule()
           
 
Method Summary
 void addClientPackageConversion(ClientPackageConversion conversion)
          Add a client package conversion.
 void addFacetExclude(java.lang.String name)
          Add a facet exclude.
 void addFacetInclude(java.lang.String name)
          Add a facet include.
 void addJsonClientPackageConversion(ClientPackageConversion conversion)
          Add a client package conversion.
 void addServerSideTypeToUse(java.lang.String serverSideTypeToUse)
          Add a server-side type to use for the client-side library.
protected  void doBuild()
          Default implementation is a no-op.
protected  void doCompile()
          Default implementation is a no-op.
 void doFreemarkerGenerate()
          Generate using Freemarker.
protected  boolean existsAnyJsonResourceMethod(java.util.List<RootResource> rootResources)
          Whether any root resources exist that produce json.
protected  java.lang.String getBeanName(ClientClassnameForMethod conversion, java.lang.String preconvert)
          Get the bean name for a specified string.
protected  java.io.File getClientCompileDir()
          The generate directory for the java client classes.
protected  java.io.File getClientGenerateDir()
          The generate directory for the java client classes.
 java.util.Map<java.lang.String,java.lang.String> getClientPackageConversions()
          The client package conversions.
 org.apache.commons.digester.RuleSet getConfigurationRules()
          An Java configuration rule set.
 java.util.Set<java.lang.String> getFacetExcludes()
          The set of facets to exclude.
 java.util.Set<java.lang.String> getFacetIncludes()
          The set of facets to include.
 java.lang.String getJarName()
          The name of the jar.
protected  java.io.File getJsonClientCompileDir()
          The generate directory for the java json client classes.
protected  java.io.File getJsonClientGenerateDir()
          The generate directory for the java json client classes.
 java.util.Map<java.lang.String,java.lang.String> getJsonClientPackageConversions()
          The json client package conversions.
 java.lang.String getJsonJarName()
          The name of the json client jar.
protected  java.util.Map<java.lang.String,java.lang.String> getJsonPackageConversions(java.util.Set<java.lang.String> uniquePackages)
          Get the list of json package conversions given the specified list of unique packages.
 java.lang.String getLabel()
          The label for the JAX-WS Client API.
 java.lang.String getName()
          The name of the deployment module.
protected  freemarker.template.ObjectWrapper getObjectWrapper()
          The object wrapper to use for the model.
 int getOrder()
          The order of execution for the deployment module.
 java.util.List<java.io.File> getProjectResourceDirectories()
          Any additional project resource directories to add to the project.
 java.util.List<java.io.File> getProjectSources()
          Any additional project source roots to add to the project.
 java.util.List<java.io.File> getProjectTestResourceDirectories()
          Any additional project resource directories to add to the project.
 java.util.List<java.io.File> getProjectTestSources()
          Any additional project test source roots to add to the project.
protected  java.io.File getServerSideDestFile(java.io.File sourceFile, com.sun.mirror.declaration.TypeDeclaration declaration)
          Get the destination for the specified declaration if the server-side type is to be used.
 java.util.Set<java.lang.String> getServerSideTypesToUse()
          The server-side types that are to be used for the client-side libraries.
protected  java.net.URL getTemplateURL(java.lang.String template)
          Get a template URL for the template of the given name.
 Validator getValidator()
          An java-client validator.
 boolean isBundleSourcesWithClasses()
          Whether to bundle the sources and the classes together.
 boolean isDisableCompile()
          Whether to disable the compilation of the java sources (default: false).
 boolean isDisabled()
          Whether this deployment module has been disabled, e.g.
 boolean isGenerateJsonJar()
          Whether to generate the JSON client jar.
 void onClassesFound(java.util.Set<java.lang.String> classes)
          Logic for handling a set of classes that were found on the Enunciate classpath.
protected  java.lang.String readResource(java.lang.String resource)
          Reads a resource into string form.
 void setBundleSourcesWithClasses(boolean bundleSourcesWithClasses)
          Whether to bundle the sources and the classes together.
 void setDisableCompile(boolean disableCompile)
          Whether to disable the compilation of the java sources (default: false).
 void setGenerateJsonJar(boolean generateJsonJar)
          Whether to generate the JSON client jar.
 void setJarName(java.lang.String jarName)
          The name of the jar.
 void setJsonJarName(java.lang.String jarName)
          The name of the json client jar.
 void setLabel(java.lang.String label)
          The label for the JAX-WS Client API.
protected  boolean useServerSide(com.sun.mirror.declaration.TypeDeclaration declaration, AntPatternMatcher matcher)
          Whether to use the server-side declaration for this declaration.
 
Methods inherited from class org.codehaus.enunciate.modules.FreemarkerDeploymentModule
close, doGenerate, getConfiguration, getModel, getModelInternal, getTemplateExceptionHandler, getTemplateLoader, initModel, processTemplate, processTemplate, processTemplate, processTemplate
 
Methods inherited from class org.codehaus.enunciate.modules.BasicDeploymentModule
debug, doPackage, getAliases, getBuildDir, getCompileDir, getEnunciate, getGenerateDir, getPackageDir, info, init, setBuildDir, setCompileDir, setDisabled, setGenerateDir, setPackageDir, step, warn
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.codehaus.enunciate.modules.DeploymentModule
close, getAliases, init, step
 

Constructor Detail

JavaClientDeploymentModule

public JavaClientDeploymentModule()
Method Detail

getName

public java.lang.String getName()
Description copied from interface: DeploymentModule
The name of the deployment module. Identifies its section in the enunciate configuration.

Specified by:
getName in interface DeploymentModule
Overrides:
getName in class BasicDeploymentModule
Returns:
"java-client"

getOrder

public int getOrder()
Description copied from interface: DeploymentModule
The order of execution for the deployment module.

Specified by:
getOrder in interface DeploymentModule
Overrides:
getOrder in class BasicDeploymentModule
Returns:
50

onClassesFound

public void onClassesFound(java.util.Set<java.lang.String> classes)
Description copied from interface: EnunciateClasspathListener
Logic for handling a set of classes that were found on the Enunciate classpath.

Specified by:
onClassesFound in interface EnunciateClasspathListener
Parameters:
classes - The classes that were found.

doFreemarkerGenerate

public void doFreemarkerGenerate()
                          throws java.io.IOException,
                                 freemarker.template.TemplateException,
                                 EnunciateException
Description copied from class: FreemarkerDeploymentModule
Generate using Freemarker. Same as FreemarkerDeploymentModule.doGenerate() but can throw a TemplateException.

Specified by:
doFreemarkerGenerate in class FreemarkerDeploymentModule
Throws:
java.io.IOException
freemarker.template.TemplateException
EnunciateException

getJsonPackageConversions

protected java.util.Map<java.lang.String,java.lang.String> getJsonPackageConversions(java.util.Set<java.lang.String> uniquePackages)
Get the list of json package conversions given the specified list of unique packages.

Parameters:
uniquePackages - The unique packages.
Returns:
The package conversions.

getClientGenerateDir

protected java.io.File getClientGenerateDir()
The generate directory for the java client classes.

Returns:
The generate directory for the java client classes.

getJsonClientGenerateDir

protected java.io.File getJsonClientGenerateDir()
The generate directory for the java json client classes.

Returns:
The generate directory for the java json client classes.

getServerSideDestFile

protected java.io.File getServerSideDestFile(java.io.File sourceFile,
                                             com.sun.mirror.declaration.TypeDeclaration declaration)
Get the destination for the specified declaration if the server-side type is to be used.

Parameters:
sourceFile - The source file.
declaration - The declaration.
Returns:
The destination file.

useServerSide

protected boolean useServerSide(com.sun.mirror.declaration.TypeDeclaration declaration,
                                AntPatternMatcher matcher)
Whether to use the server-side declaration for this declaration.

Parameters:
declaration - The declaration.
matcher - The matcher.
Returns:
Whether to use the server-side declaration for this declaration.

getBeanName

protected java.lang.String getBeanName(ClientClassnameForMethod conversion,
                                       java.lang.String preconvert)
Get the bean name for a specified string.

Parameters:
conversion - The conversion to use.
preconvert - The pre-converted fqn.
Returns:
The converted fqn.

doCompile

protected void doCompile()
                  throws EnunciateException,
                         java.io.IOException
Description copied from class: BasicDeploymentModule
Default implementation is a no-op.

Overrides:
doCompile in class BasicDeploymentModule
Throws:
EnunciateException
java.io.IOException

getClientCompileDir

protected java.io.File getClientCompileDir()
The generate directory for the java client classes.

Returns:
The generate directory for the java client classes.

getJsonClientCompileDir

protected java.io.File getJsonClientCompileDir()
The generate directory for the java json client classes.

Returns:
The generate directory for the java json client classes.

doBuild

protected void doBuild()
                throws EnunciateException,
                       java.io.IOException
Description copied from class: BasicDeploymentModule
Default implementation is a no-op.

Overrides:
doBuild in class BasicDeploymentModule
Throws:
EnunciateException
java.io.IOException

readResource

protected java.lang.String readResource(java.lang.String resource)
                                 throws java.io.IOException,
                                        EnunciateException
Reads a resource into string form.

Parameters:
resource - The resource to read.
Returns:
The string form of the resource.
Throws:
java.io.IOException
EnunciateException

getTemplateURL

protected java.net.URL getTemplateURL(java.lang.String template)
Get a template URL for the template of the given name.

Parameters:
template - The specified template.
Returns:
The URL to the specified template.

getJarName

public java.lang.String getJarName()
The name of the jar.

Returns:
The name of the jar.

getJsonJarName

public java.lang.String getJsonJarName()
The name of the json client jar.

Returns:
The name of the json client jar.

setJarName

public void setJarName(java.lang.String jarName)
The name of the jar.

Parameters:
jarName - The name of the jar.

setJsonJarName

public void setJsonJarName(java.lang.String jarName)
The name of the json client jar.

Parameters:
jarName - The name of the json client jar.

getConfigurationRules

public org.apache.commons.digester.RuleSet getConfigurationRules()
An Java configuration rule set.

Specified by:
getConfigurationRules in interface DeploymentModule
Overrides:
getConfigurationRules in class BasicDeploymentModule
Returns:
An Java configuration rule set.

getValidator

public Validator getValidator()
An java-client validator.

Specified by:
getValidator in interface DeploymentModule
Overrides:
getValidator in class BasicDeploymentModule
Returns:
An java-client validator.

getObjectWrapper

protected freemarker.template.ObjectWrapper getObjectWrapper()
Description copied from class: FreemarkerDeploymentModule
The object wrapper to use for the model.

Overrides:
getObjectWrapper in class FreemarkerDeploymentModule
Returns:
The object wrapper to use for the model.

getClientPackageConversions

public java.util.Map<java.lang.String,java.lang.String> getClientPackageConversions()
The client package conversions.

Returns:
The client package conversions.

addClientPackageConversion

public void addClientPackageConversion(ClientPackageConversion conversion)
Add a client package conversion.

Parameters:
conversion - The conversion to add.

getJsonClientPackageConversions

public java.util.Map<java.lang.String,java.lang.String> getJsonClientPackageConversions()
The json client package conversions.

Returns:
The json client package conversions.

addJsonClientPackageConversion

public void addJsonClientPackageConversion(ClientPackageConversion conversion)
Add a client package conversion.

Parameters:
conversion - The conversion to add.

getServerSideTypesToUse

public java.util.Set<java.lang.String> getServerSideTypesToUse()
The server-side types that are to be used for the client-side libraries.

Returns:
The server-side types that are to be used for the client-side libraries.

addServerSideTypeToUse

public void addServerSideTypeToUse(java.lang.String serverSideTypeToUse)
Add a server-side type to use for the client-side library.

Parameters:
serverSideTypeToUse - The server-side type to use.

getLabel

public java.lang.String getLabel()
The label for the JAX-WS Client API.

Returns:
The label for the JAX-WS Client API.

setLabel

public void setLabel(java.lang.String label)
The label for the JAX-WS Client API.

Parameters:
label - The label for the JAX-WS Client API.

isBundleSourcesWithClasses

public boolean isBundleSourcesWithClasses()
Whether to bundle the sources and the classes together.

Returns:
Whether to bundle the sources and the classes together.

setBundleSourcesWithClasses

public void setBundleSourcesWithClasses(boolean bundleSourcesWithClasses)
Whether to bundle the sources and the classes together.

Parameters:
bundleSourcesWithClasses - Whether to bundle the sources and the classes together.

isGenerateJsonJar

public boolean isGenerateJsonJar()
Whether to generate the JSON client jar.

Returns:
Whether to generate the JSON client jar.

existsAnyJsonResourceMethod

protected boolean existsAnyJsonResourceMethod(java.util.List<RootResource> rootResources)
Whether any root resources exist that produce json.

Parameters:
rootResources - The root resources.
Returns:
Whether any root resources exist that produce json.

setGenerateJsonJar

public void setGenerateJsonJar(boolean generateJsonJar)
Whether to generate the JSON client jar.

Parameters:
generateJsonJar - Whether to generate the JSON jar.

isDisabled

public boolean isDisabled()
Description copied from interface: DeploymentModule
Whether this deployment module has been disabled, e.g. in the config file. Since the discovery mechanism is used to discover the modules on the classpath, it may be necessary to be able to disable a module.

Specified by:
isDisabled in interface DeploymentModule
Overrides:
isDisabled in class BasicDeploymentModule
Returns:
Whether this deployment module has been disabled.

getProjectSources

public java.util.List<java.io.File> getProjectSources()
Description copied from interface: ProjectExtensionModule
Any additional project source roots to add to the project.

Specified by:
getProjectSources in interface ProjectExtensionModule
Returns:
Any additional project source roots to add to the project.

getProjectTestSources

public java.util.List<java.io.File> getProjectTestSources()
Description copied from interface: ProjectExtensionModule
Any additional project test source roots to add to the project.

Specified by:
getProjectTestSources in interface ProjectExtensionModule
Returns:
Any additional project test source roots to add to the project.

getProjectResourceDirectories

public java.util.List<java.io.File> getProjectResourceDirectories()
Description copied from interface: ProjectExtensionModule
Any additional project resource directories to add to the project.

Specified by:
getProjectResourceDirectories in interface ProjectExtensionModule
Returns:
Any additional project resource directories to add to the project.

getProjectTestResourceDirectories

public java.util.List<java.io.File> getProjectTestResourceDirectories()
Description copied from interface: ProjectExtensionModule
Any additional project resource directories to add to the project.

Specified by:
getProjectTestResourceDirectories in interface ProjectExtensionModule
Returns:
Any additional project resource directories to add to the project.

isDisableCompile

public boolean isDisableCompile()
Whether to disable the compilation of the java sources (default: false).

Returns:
Whether to disable the compilation of the java sources (default: false).

setDisableCompile

public void setDisableCompile(boolean disableCompile)
Whether to disable the compilation of the java sources (default: false).

Parameters:
disableCompile - Whether to disable the compilation of the java sources (default: false).

getFacetIncludes

public java.util.Set<java.lang.String> getFacetIncludes()
The set of facets to include.

Specified by:
getFacetIncludes in interface FacetAware
Returns:
The set of facets to include.

addFacetInclude

public void addFacetInclude(java.lang.String name)
Add a facet include.

Parameters:
name - The name.

getFacetExcludes

public java.util.Set<java.lang.String> getFacetExcludes()
The set of facets to exclude.

Specified by:
getFacetExcludes in interface FacetAware
Returns:
The set of facets to exclude.

addFacetExclude

public void addFacetExclude(java.lang.String name)
Add a facet exclude.

Parameters:
name - The name.