Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.codehaus.enunciate.modules.java_client
Class JavaClientDeploymentModule

java.lang.Object
  org.codehaus.enunciate.modules.BasicDeploymentModule
      org.codehaus.enunciate.modules.FreemarkerDeploymentModule
          org.codehaus.enunciate.modules.java_client.JavaClientDeploymentModule

All Implemented Interfaces:: EnunciateClasspathListener, EnunciateModelAware, DeploymentModule, FacetAware, ProjectExtensionModule

public class JavaClientDeploymentModule
extends FreemarkerDeploymentModule
implements ProjectExtensionModule, EnunciateClasspathListener, FacetAware
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
configuration
artifacts

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 "label" attribute is used to determine the name of the client-side artifact files. The default is the Enunciate project label.
The "jarName" attribute specifies the name of the jar file(s) that are to be created. If no jar name is specified, the name will be calculated from the enunciate label, or a default will be supplied.
The "jsonJarName" attribute specifies the name of the jar file(s) that are to be created for the JSON client. If no jar name is specified, the name will be calculated from the enunciate label, or a default will be supplied.
The "disableCompile" attribute prevents Enunciate from compiling its generated client source files.
The "bundleSourcesWithClasses" attribute indicates whether the sources and classes should be bundled together in a single jar.

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 "from" attribute specifies the package that is to be converted. This package will match all classes in the package as well as any subpackages of the package. This means that if "org.enunciate" were specified, it would match "org.enunciate", "org.enunciate.api", and "org.enunciate.api.impl".
The "to" attribute specifies what the package is to be converted to. Only the part of the package that matches the "from" attribute will be converted.

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:

The libraries and sources are exported under the id "java.client.library". (Note that this is a bundle, so if exporting to a directory multiple files will be exported. If exporting to a file, the bundle will be zipped first.)
The libraries and sources for the json client library are exported under the id "java.json.client.library". (Note that this is a bundle, so if exporting to a directory multiple files will be exported. If exporting to a file, the bundle will be zipped first.)

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(String name)` Add a facet exclude.
`void`	`addFacetInclude(String name)` Add a facet include.
`void`	`addJsonClientPackageConversion(ClientPackageConversion conversion)` Add a client package conversion.
`void`	`addServerSideTypeToUse(String serverSideTypeToUse)` Add a server-side type to use for the client-side library.
`protected void`	`doBuild()`
`protected void`	`doCompile()`
`void`	`doFreemarkerGenerate()`
`protected boolean`	`existsAnyJsonResourceMethod(List<RootResource> rootResources)` Whether any root resources exist that produce json.
`protected String`	`getBeanName(ClientClassnameForMethod conversion, String preconvert)` Get the bean name for a specified string.
`protected File`	`getClientCompileDir()` The generate directory for the java client classes.
`protected File`	`getClientGenerateDir()` The generate directory for the java client classes.
`Map<String,String>`	`getClientPackageConversions()` The client package conversions.
`org.apache.commons.digester.RuleSet`	`getConfigurationRules()` An Java configuration rule set.
`Set<String>`	`getFacetExcludes()` The set of facets to exclude.
`Set<String>`	`getFacetIncludes()` The set of facets to include.
`String`	`getJarName()` The name of the jar.
`protected File`	`getJsonClientCompileDir()` The generate directory for the java json client classes.
`protected File`	`getJsonClientGenerateDir()` The generate directory for the java json client classes.
`Map<String,String>`	`getJsonClientPackageConversions()` The json client package conversions.
`String`	`getJsonJarName()` The name of the json client jar.
`protected Map<String,String>`	`getJsonPackageConversions(Set<String> uniquePackages)` Get the list of json package conversions given the specified list of unique packages.
`String`	`getLabel()` The label for the JAX-WS Client API.
`String`	`getName()`
`protected freemarker.template.ObjectWrapper`	`getObjectWrapper()`
`int`	`getOrder()`
`List<File>`	`getProjectResourceDirectories()`
`List<File>`	`getProjectSources()`
`List<File>`	`getProjectTestResourceDirectories()`
`List<File>`	`getProjectTestSources()`
`protected File`	`getServerSideDestFile(File sourceFile, com.sun.mirror.declaration.TypeDeclaration declaration)` Get the destination for the specified declaration if the server-side type is to be used.
`Set<String>`	`getServerSideTypesToUse()` The server-side types that are to be used for the client-side libraries.
`protected URL`	`getTemplateURL(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()`
`boolean`	`isGenerateJsonJar()` Whether to generate the JSON client jar.
`void`	`onClassesFound(Set<String> classes)`
`protected String`	`readResource(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(String jarName)` The name of the jar.
`void`	`setJsonJarName(String jarName)` The name of the json client jar.
`void`	`setLabel(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 String getName()

Specified by:: getName in interface DeploymentModule
Overrides:: getName in class BasicDeploymentModule

Returns:: "java-client"

getOrder

public int getOrder()

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

Returns:: 50

onClassesFound

public void onClassesFound(Set<String> classes)

Specified by:: onClassesFound in interface EnunciateClasspathListener

doFreemarkerGenerate

public void doFreemarkerGenerate()
                          throws IOException,
                                 freemarker.template.TemplateException,
                                 EnunciateException

Specified by:: doFreemarkerGenerate in class FreemarkerDeploymentModule

Throws:: IOException; freemarker.template.TemplateException; EnunciateException

getJsonPackageConversions

protected Map<String,String> getJsonPackageConversions(Set<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 File getClientGenerateDir()

The generate directory for the java client classes.

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

getJsonClientGenerateDir

protected File getJsonClientGenerateDir()

The generate directory for the java json client classes.

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

getServerSideDestFile

protected File getServerSideDestFile(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 String getBeanName(ClientClassnameForMethod conversion,
                             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,
                         IOException

Overrides:: doCompile in class BasicDeploymentModule

Throws:: EnunciateException; IOException

getClientCompileDir

protected File getClientCompileDir()

The generate directory for the java client classes.

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

getJsonClientCompileDir

protected 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,
                       IOException

Overrides:: doBuild in class BasicDeploymentModule

Throws:: EnunciateException; IOException

readResource

protected String readResource(String resource)
                       throws IOException,
                              EnunciateException

Reads a resource into string form.

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

getTemplateURL

protected URL getTemplateURL(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 String getJarName()

The name of the jar.

Returns:: The name of the jar.

getJsonJarName

public String getJsonJarName()

The name of the json client jar.

Returns:: The name of the json client jar.

setJarName

public void setJarName(String jarName)

The name of the jar.

Parameters:: jarName - The name of the jar.

setJsonJarName

public void setJsonJarName(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()

Overrides:: getObjectWrapper in class FreemarkerDeploymentModule

getClientPackageConversions

public Map<String,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 Map<String,String> getJsonClientPackageConversions()

The json client package conversions.

Returns:: The json client package conversions.

addJsonClientPackageConversion

public void addJsonClientPackageConversion(ClientPackageConversion conversion)