Package org.acplt.oncrpc.apps.jrpcgen

# Class JrpcgenComplexType

java.lang.Object
org.acplt.oncrpc.apps.jrpcgen.JrpcgenDocumentable
org.acplt.oncrpc.apps.jrpcgen.JrpcgenXdrDefinition
org.acplt.oncrpc.apps.jrpcgen.JrpcgenComplexType

All Implemented Interfaces:
  `JrpcgenItem`, `JrpcgenTypeMapping`

Direct Known Subclasses:
  `JrpcgenEnum`, `JrpcgenStruct`, `JrpcgenTypedefinition`, `JrpcgenUnion`

public abstract class JrpcgenComplexType extends JrpcgenXdrDefinition implements JrpcgenTypeMapping
The complex type class is an abstract base class for complex type mappings such as structs, unions, enumerations and type definitions. At this level complex types get the following characteristics:

- A complex type cannot be a base type at the same time.
- The definition name in the x-file is used as name of the Java class, which gets generated by jrpcgen.
- The Java class implements the interface
  invalid reference

      XdrAble

  to provide the required coding methods for the mapped complex type.
- As a complex type gets mapped by a Java class, concrete complex types have to implement the method `generateJavaFile()`, which will write the implementation of the Java class.
- Within an x-file complex types are formed by XDR definitions and therefore are handled as extension to the class `JrpcgenXdrDefinition` within this library.

Author:
  Harald Wirths <hwirths@nde.ag>

## Nested Class Summary

## Nested classes/interfaces inherited from class org.acplt.oncrpc.apps.jrpcgen.JrpcgenXdrDefinition

`JrpcgenXdrDefinition.Table, JrpcgenXdrDefinition.Type`

## Field Summary

### Fields inherited from class org.acplt.oncrpc.apps.jrpcgen.JrpcgenDocumentable

`documentation`

## Constructor Summary

Constructors
Constructor
Description
`JrpcgenComplexType(String identifier, JrpcgenXdrDefinition.Type type)`
Constructs a complex type with the identifier and the type specifier passed.

## Method Summary

Modifier and Type
Method
Description
`abstract void`
`generateJavaFile()`
Concrete implementations are asked to generate a Java file containing an implementation of the Java class mapping the complex type.
`String`
`getDefinitionName()`
Returns the identifier of the complex type.
`String`
`getJavaClass()`
The complex type is mapped by a Java class.
`String`
`getJavaName()`
The Java name is equal to the definition name and therefore equal to the identifier of the complex type.
`String`
`getXdrClass()`
The Java class mapping the complex type usually implements the interface
invalid reference

    XdrAble

.
`final boolean`
`isBaseType()`
A complex type cannot be a base type at the same time.
`final boolean`
`isBooleanType()`
A complex type is always different from the type `boolean`.
`final boolean`
`isOpaqueType()`
A complex type is always different from the type `opaque`.
`final boolean`
`isStringType()`
A complex type is always different from the type `String`.
`final boolean`
`isVoid()`
A complex type is always different from the type `void`.
`void`
`writeEqualsExpression(JrpcgenJavaFile javaFile, String variableLeft, String variableRight, boolean negate)`
Writes an equals expression to the passed Java file using the passed names of the left hand side and the right hand side variable.
`void`
`writeJavaToXdr(JrpcgenJavaFile javaFile, String variable)`
At this level of a complex type the passed variable represents both the Java as well as the XDR representation and will be written as is to the passed Java file.
`void`
`writeJavaToXdr(JrpcgenJavaFile javaFile, JrpcgenJavaFile.Expression expression)`
Wirtes the passed expression to the passed Java file.
`void`
`writeXdrConstructorCall(JrpcgenJavaFile javaFile, String parameter)`
Writes a default constructor call or a constructor call with one parameter with the XDR class provided by this mapping.
`void`
`writeXdrConstructorCall(JrpcgenJavaFile javaFile, JrpcgenJavaFile.Expression parameterExpression)`
Writes a constructor call with the XDR class provided by this mapping.
`void`
`writeXdrDecodingCall(JrpcgenJavaFile javaFile, String xdrStream)`
Writes an XDR encoding call on the result of the passed expression with the passed name of an XDR decoding stream to the passed Java file.
`void`
`writeXdrDynamicVectorDecodingCall(JrpcgenJavaFile javaFile, String xdrStream)`
Writes an XDR decoding call for a dynamic vector of the mapping type to the passed Java file.
`void`
`writeXdrDynamicVectorEncodingCall(JrpcgenJavaFile javaFile, String xdrStream, String variable)`
Writes an XDR encoding call for a dynamic vector of the mapping type to the passed Java file.
`void`
`writeXdrEncodingCall(JrpcgenJavaFile javaFile, String xdrStream, String variable)`
Writes an XDR encoding call on the passed variable with the passed name of an XDR encoding stream to the passed Java file.
`void`
`writeXdrEncodingCall(JrpcgenJavaFile javaFile, String xdrStream, JrpcgenJavaFile.Expression expression)`
Writes an XDR encoding call on the result of the passed expression with the passed name of an XDR encoding stream to the passed Java file.
`void`
`writeXdrFixedVectorDecodingCall(JrpcgenJavaFile javaFile, String xdrStream, String size)`
Writes an XDR decoding call for a fixed vector of the mapping type to the passed Java file.
`void`
`writeXdrFixedVectorEncodingCall(JrpcgenJavaFile javaFile, String xdrStream, String variable, String size)`
Writes an XDR encoding call for a fixed vector of the mapping type to the passed Java file.
`void`
`writeXdrToJava(JrpcgenJavaFile javaFile, String variable)`
At this level of a complex type the passed variable represents both the Java as well as the XDR representation and will be written as is to the passed Java file.
`void`
`writeXdrVectorCodingMethods(JrpcgenJavaFile javaFile, JrpcgenContext context)`
Writes static encoding and decoding methods for fixed and dynamic vectors of the mapping to the passed Java file.

### Methods inherited from class org.acplt.oncrpc.apps.jrpcgen.JrpcgenXdrDefinition

`getIdentifier, getXdrType, isConst, isEnum, isStruct, isTypedef, isUnion`

### Methods inherited from class org.acplt.oncrpc.apps.jrpcgen.JrpcgenDocumentable

`appendDeprecatedOrNothing, appendDeprecatedOrNothing, documentationIsEmpty, documentationIsProvided, emptyDocumentation, getDocumentation, getIdentedDocu, getIdentedDocu, isDeprecated, writeDocumentation, writeDocumentation`

### Methods inherited from class java.lang.Object

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

## Constructor Details

### JrpcgenComplexType

public JrpcgenComplexType(String identifier, JrpcgenXdrDefinition.Type type)
Constructs a complex type with the identifier and the type specifier passed.

Parameters:
  `identifier` - The identifier of the complex type.
  `type` - The type specifier of the complex type, which will be one of
  - `JrpcgenXdrDefinition.Type.ENUM`
  - `JrpcgenXdrDefinition.Type.STRUCT`
  - `JrpcgenXdrDefinition.Type.UNION`
  - `JrpcgenXdrDefinition.Type.TYPEDEF`

## Method Details

### generateJavaFile

public abstract void generateJavaFile()
Concrete implementations are asked to generate a Java file containing an implementation of the Java class mapping the complex type.

### isVoid

public final boolean isVoid()
A complex type is always different from the type `void`.

Specified by:
  `isVoid` in interface `JrpcgenTypeMapping`
Returns:
  `false`, always.

### isBaseType

public final boolean isBaseType()
A complex type cannot be a base type at the same time.

Specified by:
  `isBaseType` in interface `JrpcgenTypeMapping`
Returns:
  `false`, always.

### isBooleanType

public final boolean isBooleanType()
A complex type is always different from the type `boolean`.

Specified by:
  `isBooleanType` in interface `JrpcgenTypeMapping`
Returns:
  `false`, always.

### isStringType

public final boolean isStringType()
A complex type is always different from the type `String`.

Specified by:
  `isStringType` in interface `JrpcgenTypeMapping`
Returns:
  `false`, always.

### isOpaqueType

public final boolean isOpaqueType()
A complex type is always different from the type `opaque`.

Specified by:
  `isOpaqueType` in interface `JrpcgenTypeMapping`
Returns:
  `false`, always.

### getDefinitionName

public String getDefinitionName()
Returns the identifier of the complex type.

Specified by:
  `getDefinitionName` in interface `JrpcgenTypeMapping`
Returns:
  The identifier of the complex type.

### getJavaName

public String getJavaName()
The Java name is equal to the definition name and therefore equal to the identifier of the complex type.

Specified by:
  `getJavaName` in interface `JrpcgenTypeMapping`
Returns:
  The identifier of the complex type.

### getJavaClass

public String getJavaClass()
The complex type is mapped by a Java class. The name of the class is equal to teh definition name of the complex type and therefore equal to the identifier of the complex type.

Specified by:
  `getJavaClass` in interface `JrpcgenTypeMapping`
Returns:
  The identifier of the complex type.

### getXdrClass

public String getXdrClass()
The Java class mapping the complex type usually implements the interface
invalid reference

    XdrAble

. Therefore the name of the XDR class is equal to the definition name and the identifier of the complex type, respectively.

Specified by:
  `getXdrClass` in interface `JrpcgenTypeMapping`
Returns:
  The identifier of the complex type.

### writeXdrConstructorCall

public void writeXdrConstructorCall(JrpcgenJavaFile javaFile, String parameter)
Writes a default constructor call or a constructor call with one parameter with the XDR class provided by this mapping. Passing `null` as value of the parameter `parameter` will result in a default constructor call written to the passed Java file. Otherwise the value of the parameter `parameter` will be written as parameter to the constuctor call.

Specified by:
  `writeXdrConstructorCall` in interface `JrpcgenTypeMapping`
Parameters:
  `javaFile` - The Java file, where the constructor call is going to be placed.
  `parameter` - `null` to generate a default constructor call, a parameter name to generate a constructor call with one parameter.

### writeXdrConstructorCall

public void writeXdrConstructorCall(JrpcgenJavaFile javaFile, JrpcgenJavaFile.Expression parameterExpression)
Writes a constructor call with the XDR class provided by this mapping. The parameter expression is intended to write an expression, which evaluates to a parameter to the constructor call.

Specified by:
  `writeXdrConstructorCall` in interface `JrpcgenTypeMapping`
Parameters:
  `javaFile` - The Java file, where the constructor call is going to be placed.
  `parameterExpression` - An expression to be called with the passed Java file, when the expression is going to be placed in the Java file.

### writeJavaToXdr

public void writeJavaToXdr(JrpcgenJavaFile javaFile, String variable)
At this level of a complex type the passed variable represents both the Java as well as the XDR representation and will be written as is to the passed Java file. No conversion will take place.

Specified by:
  `writeJavaToXdr` in interface `JrpcgenTypeMapping`
Parameters:
  `javaFile` - The Java file, where the variable is going to be placed.
  `variable` - The name of a variable in Java representation.

### writeJavaToXdr

public void writeJavaToXdr(JrpcgenJavaFile javaFile, JrpcgenJavaFile.Expression expression)
Wirtes the passed expression to the passed Java file. At this level of a complex type no conversion takes place and therefore the passed expression will be written as is. The expression is expected to result in a value of the mapped type.

Specified by:
  `writeJavaToXdr` in interface `JrpcgenTypeMapping`
Parameters:
  `javaFile` - The Java file, where the passed expression is going to be placed.
  `expression` - An expression to be called with the passed Java file.

### writeXdrToJava

public void writeXdrToJava(JrpcgenJavaFile javaFile, String variable)
At this level of a complex type the passed variable represents both the Java as well as the XDR representation and will be written as is to the passed Java file. No conversion will take place.

Specified by:
  `writeXdrToJava` in interface `JrpcgenTypeMapping`
Parameters:
  `javaFile` - The Java file, where the result is going to be placed.
  `variable` - The name of a variable in XDR representation.

### writeXdrEncodingCall

public void writeXdrEncodingCall(JrpcgenJavaFile javaFile, String xdrStream, String variable)
Writes an XDR encoding call on the passed variable with the passed name of an XDR encoding stream to the passed Java file. At this level of complex types the mapping type implements the interface
invalid reference

    XdrAble

and therefore the XDR encoding call will be similar to `variable.xdrEncode(xdrStream)`.

Specified by:
  `writeXdrEncodingCall` in interface `JrpcgenTypeMapping`
Parameters:
  `javaFile` - The Java file, where the XDR encoding call is going to be placed.
  `xdrStream` - The name of the XDR encoding stream instance to be used in the statement.
  `variable` - The name of the variable to be used in the statement.

### writeXdrEncodingCall

public void writeXdrEncodingCall(JrpcgenJavaFile javaFile, String xdrStream, JrpcgenJavaFile.Expression expression)
Writes an XDR encoding call on the result of the passed expression with the passed name of an XDR encoding stream to the passed Java file. At this level of complex types the result of the expression is expected to be of the mapping type, which implements the interface
invalid reference

    XdrAble

. Therefore the XDR encoding call will be similar to `expression.xdrEncode(xdrStream)`.

Specified by:
  `writeXdrEncodingCall` in interface `JrpcgenTypeMapping`
Parameters:
  `javaFile` - The Java file, where the XDR encoding call is going to be placed.
  `xdrStream` - The name of the XDR encoding stream instance to be used in the statement.
  `expression` - An expression to be called with the passed Java file, when the expression is going to be placed in the Java file.

### writeXdrFixedVectorEncodingCall

public void writeXdrFixedVectorEncodingCall(JrpcgenJavaFile javaFile, String xdrStream, String variable, String size)
Writes an XDR encoding call for a fixed vector of the mapping type to the passed Java file. The passed name of an XDR encoding stream, the passed name of the vector variable and the passed size string indicating the size of the fixed vector are used to form the XDR encoding call. This method expects the existence of the static method `xdrEncodeFixedVector(XdrEncodingStream, MappingType, int)` in the generated code of the mapping type `MappingType` as done by a call to the method `writeXdrVectorCodingMethods(JrpcgenJavaFile, JrpcgenContext)` within the implementation of the method `generateJavaFile()`. Thereby `MappingType` is a placeholder for the name of concrete mapping type at this point.

Specified by:
  `writeXdrFixedVectorEncodingCall` in interface `JrpcgenTypeMapping`
Parameters:
  `javaFile` - The Java file, where the XDR encoding call is going to be placed.
  `xdrStream` - The name of the XDR encoding instance to be used in the statement.
  `variable` - The name of the variable to be used in the statement.
  `size` - A string specifying the size of the fixed vector.

### writeXdrDynamicVectorEncodingCall

public void writeXdrDynamicVectorEncodingCall(JrpcgenJavaFile javaFile, String xdrStream, String variable)
Writes an XDR encoding call for a dynamic vector of the mapping type to the passed Java file. The passed name of an XDR encoding stream and the passed name of the vector variable are used to form the XDR encoding call. This method expects the existence of the static method `xdrEncodeDynamicVector(XdrEncodingStream, MappingType)` in the generated code of the mapping type as done by a call to the method
invalid reference

    #wirteXdrVectorCodingMethods(JrpcgenJavaFile, JrpcgenContext)

within the implementation of the method `generateJavaFile()`. Thereby `MappingType` is a placeholder for the name of the concrete mapping type at this point.

Specified by:
  `writeXdrDynamicVectorEncodingCall` in interface `JrpcgenTypeMapping`
Parameters:
  `javaFile` - The Java file, where the XDR encoding call is going to be placed.
  `xdrStream` - The name of the XDR encoding instance to be used in the statement.
  `variable` - The name of the variable to be used in the statement.

### writeXdrDecodingCall

public void writeXdrDecodingCall(JrpcgenJavaFile javaFile, String xdrStream)
Writes an XDR encoding call on the result of the passed expression with the passed name of an XDR decoding stream to the passed Java file. At this level of complex types the mapping type implements the interface
invalid reference

    XdrAble

and therefore the XDR decoding call will be similar to an constructor call with the name of the XDR decoding stream as parameter.

Specified by:
  `writeXdrDecodingCall` in interface `JrpcgenTypeMapping`
Parameters:
  `javaFile` - The Java file, where the XDR decoding call is going to be placed.
  `xdrStream` - The name of the XDR decoding stream instance to be used in the statement.

### writeXdrFixedVectorDecodingCall

public void writeXdrFixedVectorDecodingCall(JrpcgenJavaFile javaFile, String xdrStream, String size)
Writes an XDR decoding call for a fixed vector of the mapping type to the passed Java file. The passed name of an XDR decoding stream and the passed size string indicating the size of fixed vector are used to form the XDR decoding call. This method expects the existence of the static method `xdrDecodeFixedVector(XdrDecodingStream, int)` within the implementation of the generated code of the mapping type `MappingType` as done by a call to the method `writeXdrVectorCodingMethods(JrpcgenJavaFile, JrpcgenContext)` within the implementation of the method `generateJavaFile()`. Thereby `MappingType` is a placeholder for the name of the concrete mapping type at this point.

Specified by:
  `writeXdrFixedVectorDecodingCall` in interface `JrpcgenTypeMapping`
Parameters:
  `javaFile` - The Java file, where the XDR decoding call is going to be placed.
  `xdrStream` - The name of the XDR decoding stream instance to be used in the statement.
  `size` - A string specifying the size of the fixed vector.

### writeXdrDynamicVectorDecodingCall

public void writeXdrDynamicVectorDecodingCall(JrpcgenJavaFile javaFile, String xdrStream)
Writes an XDR decoding call for a dynamic vector of the mapping type to the passed Java file. The passed name of an XDR decoding stream is used to to form the XDR decoding call. This method expects the existence of the static method `xdrDecodeDynamicVector(XdrDecodingStream)` in the generated code of the mapping type as done by a call to method `writeXdrVectorCodingMethods(JrpcgenJavaFile, JrpcgenContext)` within the implementation of the method `generateJavaFile()`.

Specified by:
  `writeXdrDynamicVectorDecodingCall` in interface `JrpcgenTypeMapping`
Parameters:
  `javaFile` - The Java file, where the XDR decoding call is going to be placed.
  `xdrStream` - The name of the XDR decoding stream instance to be used in the statement.

### writeEqualsExpression

public void writeEqualsExpression(JrpcgenJavaFile javaFile, String variableLeft, String variableRight, boolean negate)
Writes an equals expression to the passed Java file using the passed names of the left hand side and the right hand side variable. The negate parameter controls whether the statement evaluates to `true` on equality or on inequality. At this level of complex types the generated code will be similar to

     java.utils.Objects.equals(variableLeft, variableRight)

for `negate=false` and

     ! java.utils.Objects.equals(variableLeft, variableRight)

for `negate=true`.

Specified by:
  `writeEqualsExpression` in interface `JrpcgenTypeMapping`
Parameters:
  `javaFile` - The Java file, where the equality expression is going to be placed.
  `variableLeft` - The name of the variable to be used as the left hand side in the statement.
  `variableRight` - The name of the variable to be used as the right hand side in the statement.
  `negate` - `false` to let the resulting statement return `true` on equality, `true` to let the resulting statement return `true` on inequality.

### writeXdrVectorCodingMethods

public void writeXdrVectorCodingMethods(JrpcgenJavaFile javaFile, JrpcgenContext context)
Writes static encoding and decoding methods for fixed and dynamic vectors of the mapping to the passed Java file. A call to this method is intended during the generation of the class file of the mapping type.

However, the static encoding and decoding methods for fixed and dynamic vectors of the mapping type will be written only if they are required as a result of the foregoing parsing process. During the parsing phase vector uses of the mapping type are recognized and stored in maps for types in fixed and dynamic vector uses, respectively. The rules of generation are as follows:

- Nothing will be written, if the mapping type is neither listed in the map of types in fixed vector use nor listed in the map of the types in dynamic vector use.
- The static encoding and decoding methods for dynamic vectors of the mapping type will be written, if the mapping type is used at least in one of the both fixed or dynamic vectors.
- The static encoding methods for fixed and dynamic vectors of the mapping type will be written, if the mapping type is used at least in a fixed vector.

Parameters:
  `javaFile` - The Java file, where the static methods are going to be placed.
  `context` - The context of the current jrpcgen run.