com.helger.jcodemodel

Class JCodeModel

java.lang.Object

com.helger.jcodemodel.JCodeModel

public final class JCodeModel
extends Object

Root of the code DOM.

Here's your typical CodeModel application.

 JCodeModel cm = new JCodeModel();

 // generate source code by populating the 'cm' tree.
 cm._class(...);
 ...

 // write them out
 cm.build(new File("."));
 

Every CodeModel node is always owned by one JCodeModel object at any given time (which can be often accessed by the owner() method.) As such, when you generate Java code, most of the operation works in a top-down fashion. For example, you create a class from JCodeModel, which gives you a JDefinedClass. Then you invoke a method on it to generate a new method, which gives you JMethod, and so on. There are a few exceptions to this, most notably building IJExpressions, but generally you work with CodeModel in a top-down fashion. Because of this design, most of the CodeModel classes aren't directly instanciable.

Where to go from here?

Most of the time you'd want to populate new type definitions in a JCodeModel. See _class(String, EClassType).

Field Summary

Fields

Modifier and Type	Field and Description
JPrimitiveType	BOOLEAN
static Map<Class<?>,Class<?>>	boxToPrimitive The reverse look up for primitiveToBox.
JPrimitiveType	BYTE
JPrimitiveType	CHAR
JPrimitiveType	DOUBLE
JPrimitiveType	FLOAT
JPrimitiveType	INT
protected boolean	isCaseSensitiveFileSystem If the flag is true, we will consider two classes "Foo" and "foo" as a collision.
JPrimitiveType	LONG
JNullType	NULL Obtains a reference to the special "null" type.
static Map<Class<?>,Class<?>>	primitiveToBox Conversion from primitive type Class (such as Integer.TYPE) to its boxed type (such as Integer.class).
JPrimitiveType	SHORT
JPrimitiveType	VOID

Constructor Summary

Constructors

Constructor and Description
JCodeModel()

Method Summary

Modifier and Type	Method and Description
JDefinedClass	_class(int nMods, String sFullyQualifiedClassName) Creates a new generated class.
JDefinedClass	_class(int nMods, String sFullyQualifiedClassName, EClassType eClassType) Creates a new generated class.
JDefinedClass	_class(String sFullyQualifiedClassName) Creates a new generated class.
JDefinedClass	_class(String sFullyQualifiedClassName, EClassType eClassType) Creates a new generated class.
JDefinedClass	_getClass(String sFullyQualifiedClassName) Gets a reference to the already created generated class.
JPackage	_package(String name) Add a package to the list of packages to be generated
AbstractJType	_ref(Class<?> c) Like ref(Class) but also handling primitive types!
JAnonymousClass	anonymousClass(AbstractJClass aBaseClass) Creates a new anonymous class.
JAnonymousClass	anonymousClass(Class<?> aBaseClass) Creates a new anonymous class.
void	build(AbstractCodeWriter out) A convenience method for build(out,out).
void	build(AbstractCodeWriter source, AbstractCodeWriter resource) Generates Java source code.
void	build(File destDir) A convenience method for build(destDir,System.out).
void	build(File srcDir, File resourceDir) A convenience method for build(srcDir,resourceDir,System.out).
void	build(File srcDir, File resourceDir, PrintStream status) Generates Java source code.
void	build(File destDir, PrintStream status) Generates Java source code.
boolean	buildsErrorTypeRefs() Check if any error-types leaked into output Java-sources.
int	countArtifacts()
JDirectClass	directClass(EClassType eClassType, String sName) Creates a dummy, unknown JDirectClass that represents a given name.
JDirectClass	directClass(String sName) Creates a dummy, unknown JDirectClass that represents a given name.
JErrorClass	errorClass(String sMessage) Creates a dummy, error AbstractJClass that can only be referenced from hidden classes.
JErrorClass	errorClass(String sMessage, String sName) Creates a dummy, error AbstractJClass that can only be referenced from hidden classes.
Charset	getBuildingCharset()
String	getBuildingNewLine()
protected static boolean	getFileSystemCaseSensitivity()
Iterator<JPackage>	packages()
AbstractJType	parseType(String name) Obtains a type object from a type name.
AbstractJClass	ref(Class<?> clazz) Obtains a reference to an existing class from its Class object.
AbstractJClass	ref(String sFullyQualifiedClassName) Obtains a reference to an existing class from its fully-qualified class name.
JDefinedClass	ref(TypeElement element, Elements elementUtils) Obtains a reference to a processable class from its TypeElement description.
JDefinedClass	refWithErrorTypes(TypeElement element, Elements elementUtils) Obtains a reference to a processable class from its TypeElement description.
JPackage	rootPackage()
JCodeModel	setBuildingCharset(Charset aCharset) Set the charset to be used for emitting files.
JCodeModel	setBuildingNewLine(String sNewLine) Set the new line string to be used for emitting source files.
AbstractJClass	wildcard()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

primitiveToBox

public static final Map<Class<?>,Class<?>> primitiveToBox

Conversion from primitive type Class (such as Integer.TYPE) to its boxed type (such as Integer.class). It's an unmodifiable map.

boxToPrimitive

public static final Map<Class<?>,Class<?>> boxToPrimitive

The reverse look up for primitiveToBox. It's an unmodifiable map.

NULL

public final JNullType NULL

Obtains a reference to the special "null" type.

BOOLEAN

public final JPrimitiveType BOOLEAN

BYTE

public final JPrimitiveType BYTE

CHAR

public final JPrimitiveType CHAR

DOUBLE

public final JPrimitiveType DOUBLE

FLOAT

public final JPrimitiveType FLOAT

INT

public final JPrimitiveType INT

LONG

public final JPrimitiveType LONG

SHORT

public final JPrimitiveType SHORT

VOID

public final JPrimitiveType VOID

isCaseSensitiveFileSystem

protected final boolean isCaseSensitiveFileSystem

If the flag is true, we will consider two classes "Foo" and "foo" as a collision.

Constructor Detail

JCodeModel

public JCodeModel()

Method Detail

getFileSystemCaseSensitivity

protected static boolean getFileSystemCaseSensitivity()

_package

@Nonnull
public JPackage _package(@Nonnull
                                   String name)

Add a package to the list of packages to be generated

Parameters:

name - Name of the package. Use "" to indicate the root package.

Returns:

Newly generated package

rootPackage

@Nonnull
public final JPackage rootPackage()

packages

@Nonnull
public Iterator<JPackage> packages()

Returns:

an iterator that walks the packages defined using this code writer.

_class

@Nonnull
public JDefinedClass _class(int nMods,
                                      @Nonnull
                                      String sFullyQualifiedClassName,
                                      @Nonnull
                                      EClassType eClassType)
                               throws JClassAlreadyExistsException

Creates a new generated class.

Parameters:

nMods - Modifiers to use

sFullyQualifiedClassName - FQCN

eClassType - Class type to use (enum/class/interface/annotation)

Returns:

New JDefinedClass

Throws:

JClassAlreadyExistsException - When the specified class/interface was already created.

_class

@Nonnull
public JDefinedClass _class(@Nonnull
                                      String sFullyQualifiedClassName)
                               throws JClassAlreadyExistsException

Creates a new generated class.

Parameters:

sFullyQualifiedClassName - FQCN

Returns:

New JDefinedClass

Throws:

JClassAlreadyExistsException - When the specified class/interface was already created.

_class

@Nonnull
public JDefinedClass _class(int nMods,
                                      @Nonnull
                                      String sFullyQualifiedClassName)
                               throws JClassAlreadyExistsException

Creates a new generated class.

Parameters:

nMods - Modifiers to use

sFullyQualifiedClassName - FQCN

Returns:

New JDefinedClass

Throws:

JClassAlreadyExistsException - When the specified class/interface was already created.

_class

@Nonnull
public JDefinedClass _class(@Nonnull
                                      String sFullyQualifiedClassName,
                                      @Nonnull
                                      EClassType eClassType)
                               throws JClassAlreadyExistsException

Creates a new generated class.

Parameters:

sFullyQualifiedClassName - FQCN

eClassType - Class type to use (enum/class/interface/annotation)

Returns:

New JDefinedClass

Throws:

JClassAlreadyExistsException - When the specified class/interface was already created.

directClass

@Nonnull
public JDirectClass directClass(@Nonnull
                                          String sName)

Creates a dummy, unknown JDirectClass that represents a given name.
This method is useful when the code generation needs to include the user-specified class that may or may not exist, and only thing known about it is a class name.

Parameters:

sName - The fully qualified name of the class. When using type parameters please use parseType(String) instead!

Returns:

New JDirectClass

directClass

@Nonnull
public JDirectClass directClass(@Nonnull
                                          EClassType eClassType,
                                          @Nonnull
                                          String sName)

Creates a dummy, unknown JDirectClass that represents a given name.
This method is useful when the code generation needs to include the user-specified class that may or may not exist, and only thing known about it is a class name.

Parameters:

eClassType - Class type to use.

sName - The fully qualified name of the class. When using type parameters please use parseType(String) instead!

Returns:

New JDirectClass

errorClass

@Nonnull
public JErrorClass errorClass(@Nonnull
                                        String sMessage)

Creates a dummy, error AbstractJClass that can only be referenced from hidden classes.

This method is useful when the code generation needs to include some error class that should never leak into actually written code.

Error-types represents holes or place-holders that can't be filled. References to error-classes can be used in hidden class-models. Such classes should never be actually written but can be somehow used during code generation. Use JCodeModel#buildsErrorTypeRefs method to test if your generated Java-sources contains references to error-types.

You should probably always check generated code with JCodeModel#buildsErrorTypeRefs method if you use any error-types.

Most of error-types methods throws JErrorClassUsedException unchecked exceptions. Be careful and use AbstractJType#isError method to check for error-types before actually using it's methods.

Parameters:

sMessage - some free form text message to identify source of error

Returns:

New JErrorClass

See Also:

buildsErrorTypeRefs(), JErrorClass

errorClass

@Nonnull
public JErrorClass errorClass(@Nonnull
                                        String sMessage,
                                        @Nullable
                                        String sName)

Creates a dummy, error AbstractJClass that can only be referenced from hidden classes.

This method is useful when the code generation needs to include some error class that should never leak into actually written code.

Error-types represents holes or place-holders that can't be filled. References to error-classes can be used in hidden class-models. Such classes should never be actually written but can be somehow used during code generation. Use JCodeModel#buildsErrorTypeRefs method to test if your generated Java-sources contains references to error-types.

You should probably always check generated code with JCodeModel#buildsErrorTypeRefs method if you use any error-types.

Most of error-types methods throws JErrorClassUsedException unchecked exceptions. Be careful and use AbstractJType#isError method to check for error-types before actually using it's methods.

Parameters:

sName - name of missing class if it is known

sMessage - some free form text message to identify source of error

Returns:

New JErrorClass

See Also:

buildsErrorTypeRefs(), JErrorClass

buildsErrorTypeRefs

public boolean buildsErrorTypeRefs()

Check if any error-types leaked into output Java-sources.

Returns:

true if so

See Also:

errorClass(String)

_getClass

@Nullable
public JDefinedClass _getClass(@Nonnull
                                          String sFullyQualifiedClassName)

Gets a reference to the already created generated class.

Parameters:

sFullyQualifiedClassName - FQCN

Returns:

null If the class is not yet created.

See Also:

JPackage._getClass(String)

anonymousClass

@Nonnull
public JAnonymousClass anonymousClass(@Nonnull
                                                AbstractJClass aBaseClass)

Creates a new anonymous class.

Parameters:

aBaseClass - Base class

Returns:

New JAnonymousClass

anonymousClass

@Nonnull
public JAnonymousClass anonymousClass(@Nonnull
                                                Class<?> aBaseClass)

Creates a new anonymous class.

Parameters:

aBaseClass - Base class

Returns:

New JAnonymousClass

getBuildingCharset

@Nullable
public Charset getBuildingCharset()

Returns:

The default charset used for building. null means system default.

setBuildingCharset

@Nonnull
public JCodeModel setBuildingCharset(@Nullable
                                               Charset aCharset)

Set the charset to be used for emitting files.

Parameters:

aCharset - The charset to be used. May be null to indicate the use of the system default.

Returns:

this for chaining

getBuildingNewLine

public String getBuildingNewLine()

Returns:

The newline string to be used. Defaults to system default

setBuildingNewLine

@Nonnull
public JCodeModel setBuildingNewLine(@Nonnull
                                               String sNewLine)

Set the new line string to be used for emitting source files.

Parameters:

sNewLine - The new line string to be used. May neither be null nor empty.

Returns:

this for chaining

build

public void build(@Nonnull
                  File destDir,
                  @Nullable
                  PrintStream status)
           throws IOException

Generates Java source code. A convenience method for build(destDir,destDir,status).

Parameters:

destDir - source files and resources are generated into this directory.

status - if non-null, progress indication will be sent to this stream.

Throws:

IOException - on IO error

build

public void build(@Nonnull
                  File srcDir,
                  @Nonnull
                  File resourceDir,
                  @Nullable
                  PrintStream status)
           throws IOException

Generates Java source code. A convenience method that calls build(AbstractCodeWriter,AbstractCodeWriter).

Parameters:

srcDir - Java source files are generated into this directory.

resourceDir - Other resource files are generated into this directory.

status - Progress stream. May be null.

Throws:

IOException - on IO error if non-null, progress indication will be sent to this stream.

build

public void build(@Nonnull
                  File destDir)
           throws IOException

A convenience method for build(destDir,System.out).

Parameters:

destDir - source files and resources are generated into this directory.

Throws:

IOException - on IO error

build

public void build(@Nonnull
                  File srcDir,
                  @Nonnull
                  File resourceDir)
           throws IOException

A convenience method for build(srcDir,resourceDir,System.out).

Parameters:

srcDir - Java source files are generated into this directory.

resourceDir - Other resource files are generated into this directory.

Throws:

IOException - on IO error

build

public void build(@Nonnull
                  AbstractCodeWriter out)
           throws IOException

A convenience method for build(out,out).

Parameters:

out - Source code and resource writer

Throws:

IOException - on IO error

build

public void build(@Nonnull
                  AbstractCodeWriter source,
                  @Nonnull
                  AbstractCodeWriter resource)
           throws IOException

Generates Java source code.

Parameters:

source - Source code writer

resource - Resource writer

Throws:

IOException - on IO error

countArtifacts

@Nonnegative
public int countArtifacts()

Returns:

the number of files to be generated if build(java.io.File, java.io.PrintStream) is invoked now.

ref

@Nonnull
public AbstractJClass ref(@Nonnull
                                    Class<?> clazz)

Obtains a reference to an existing class from its Class object.

The parameter may not be primitive.

Parameters:

clazz - Existing class to reference

Returns:

Singleton reference to this class. Might be a JReferencedClass or a JArrayClass

See Also:

for the version that handles more cases.

ref

@Nonnull
public JDefinedClass ref(@Nonnull
                                   TypeElement element,
                                   @Nonnull
                                   Elements elementUtils)
                            throws ErrorTypeFound,
                                   CodeModelBuildingException

Obtains a reference to a processable class from its TypeElement description.

Annotation processors can get access of TypeElement objects during annotation processing. These TypeElement objects can be used with jcodemodel as a references to classes.

This method result-class definition can never include references to "error"-types. Error-types araise during annotation processing when something is not fully defined.

You can post-pond annotation processing for later stages of annotation processor hoping that all error-types will become defined on some annotation processing stage at last. You can catch ErrorTypeFound exception to achieve this.

Parameters:

element - Processable class to reference

elementUtils - Utility functions to handle Element-objects

Returns:

Singleton reference to this class.

Throws:

ErrorTypeFound - if some classes are not fully defined during annotation processing.

CodeModelBuildingException - In case of an internal error (?)

See Also:

JCodeModelJavaxLangModelAdapter, refWithErrorTypes(TypeElement,Elements)

refWithErrorTypes

@Nonnull
public JDefinedClass refWithErrorTypes(@Nonnull
                                                 TypeElement element,
                                                 @Nonnull
                                                 Elements elementUtils)
                                          throws CodeModelBuildingException

Obtains a reference to a processable class from its TypeElement description.

Annotation processors can get access of TypeElement objects during annotation processing. These TypeElement objects can be used with jcodemodel as a references to classes.

This method result-class definition can include references to "error"-types. Error-types araise during annotation processing when something is not fully defined.

Sometimes direct treatment of error-types is required. You can use AbstractJType.isError() and buildsErrorTypeRefs() methods to handle error-types and to prevent error-types to leak into generated code.

Parameters:

element - Processable class to reference

elementUtils - Utility functions to handle Element-objects

Returns:

Singleton reference to this class.

Throws:

CodeModelBuildingException - In case of an internal error (?)

See Also:

JCodeModelJavaxLangModelAdapter, ref(TypeElement, Elements), JErrorClass, buildsErrorTypeRefs()

_ref

@Nonnull
public AbstractJType _ref(@Nonnull
                                    Class<?> c)

Like ref(Class) but also handling primitive types!

Parameters:

c - Class to be referenced

Returns:

primitive or class

ref

@Nonnull
public AbstractJClass ref(@Nonnull
                                    String sFullyQualifiedClassName)

Obtains a reference to an existing class from its fully-qualified class name.
First, this method attempts to load the class of the given name. If that fails, we assume that the class is derived straight from Object, and return a AbstractJClass.

Parameters:

sFullyQualifiedClassName - FQCN

Returns:

Singleton reference to this class. Might be a JReferencedClass or a JArrayClass or a JDirectClass

wildcard

@Nonnull
public AbstractJClass wildcard()

Returns:

Singleton AbstractJClass representation for "?", which is equivalent to "? extends Object".

parseType

@Nonnull
public AbstractJType parseType(@Nonnull
                                         String name)

Obtains a type object from a type name.

This method handles primitive types, arrays, and existing Classes.

Parameters:

name - Type name to parse

Returns:

The internal representation of the specified name. Might be a JArrayClass, a JPrimitiveType, a JReferencedClass, a JNarrowedClass