org.sandev.generator
Class ProtocolBufferGenerator

java.lang.Object
  org.sandev.generator.GeneratorCommon
      org.sandev.generator.AggregateGeneratorBase
          org.sandev.generator.ProtocolBufferGenerator

All Implemented Interfaces:

org.sandev.sandbuild.SandGenerator

public class ProtocolBufferGenerator
extends AggregateGeneratorBase
implements org.sandev.sandbuild.SandGenerator

Write a protocol buffer declaration file for our defined messages. Protocol Buffers are Google's data interchange format. For more information see their announcement.

Basically what this does is go through all the struct declarations and write the corresponding prototype declarations for the derived messages to appname.proto in the apps util directory. Also included in the file is the receivable messages in the given node declaration, if specified in the generator call. The generated .proto file will have all the messages and whatever the app can receive if functioning as a web service. To use the .proto file you will need to

1. Run the protoc compiler as part of the application build to create the protobuf classes. The protoc compiler is not part of the default SAND build.
2. Write a protbuf object to SAND message converter utility. You can write this manually if there are only one or two messages to convert, otherwise use a generator.
3. Implement the application receive/response endpoints for the protocol being supported (RPC, web service, messaging, function call or whatever), based on the stubs provided from protoc and any extensions to it that you are using.

By default all fields are declared as optional (or repeated for arrays). By default IDs are assigned in the order that the fields are declared starting from 1. The default field type mappings are:

SAND type	.proto type
int	int32
long	int64
double	double
Date	Date (defined base type)
String	string

The default ID and type can be overridden using the protobuf SAND field tag. For example

@sand.protobuf 3 sint32 required

defines the field as a required signed int with ID 3.

Enum declarations are not currently generated. We are currently using plain int values instead so that if you add a new enum value, both the sender and receiver can continue to communicate without having to regenerate the serialization. At the time of this writing there are also some limitations to Protocol Buffers declarations that are worth noting:

1. Interfaces are not supported. So for example a SandUpdateMessage[] field cannot be serialized.
2. Service method declarations cannot be overloaded. So for example declaring receive(SomeMessageType) and receive(OtherMessageType) is not allowed by protoc.
3. At least for java, the generator builds one .java file with all the class declarations contained in it.

Field Summary

Fields inherited from class org.sandev.generator.AggregateGeneratorBase

extra

Fields inherited from class org.sandev.generator.GeneratorCommon

CONTEXT_CONFIGURATION, CONTEXT_CONTROL, CONTEXT_FRAMEWORK, CONTEXT_MESSAGING, CONTEXT_PERSISTENCE, CONTEXT_UI, DEFAULT_LINE_LENGTH, MESSAGE_INTERFACES

Constructor Summary

ProtocolBufferGenerator()

Method Summary

protected java.lang.String	getFileSpec(java.io.File baseDir) Return lastApp/src/TLD/domain/appname/util/PBMsgs.proto for the triggering build.
protected java.lang.String	getProtoType(java.lang.String typename) Return the protobuf type for the given SAND type.
protected boolean	hasContainedInterfaces(com.sun.javadoc.FieldDoc[] fields, org.sandev.sandbuild.SandDecl[] decls, com.sun.javadoc.ClassDoc cd) Return true if the given fields include interfaces.
protected void	writeBaseTypes(java.io.PrintStream out) Write the message declarations for the basic types we require.
protected void	writeFile(java.io.PrintStream out, org.sandev.sandbuild.SandDecl[] decls) Write the proto declarations source file.
protected void	writeMessageDecl(java.io.PrintStream out, java.lang.String className, com.sun.javadoc.ClassDoc cd, com.sun.javadoc.FieldDoc[] fields) Write a struct message declaration
protected void	writeMessageDecls(java.io.PrintStream out, org.sandev.sandbuild.SandDecl[] decls) Write the declarations for each of the defined structs.
protected void	writeReceiverDecls(java.io.PrintStream out, org.sandev.sandbuild.SandDecl[] decls)

Methods inherited from class org.sandev.generator.AggregateGeneratorBase

addSandAttrValToDecls, cleanup, cleanupSecondaryFiles, generate, getExtra, setExtra, writeSecondaryFiles

Methods inherited from class org.sandev.generator.GeneratorCommon

capitalize, copyfile, deletefile, filterHTMLLine, findStructDeclByShortname, getDeclaredFields, getFields, getInheritanceHierarchy, getLastAppProject, getLastUtilDir, getLongInstanceName, getPrintStream, getSandProject, getShortInstanceName, getUtilPackage, getVisibleFields, hasSubStructs, isArray, isBasic, isLongReferenceArray, isMessageInterface, isParentAbstract, isPrimitive, isRootStruct, isVowel, log, nextToken, pluralize, rangeEscape, removePlatformDecls, trackFileDelete, trackFileWrite, uncapitalize, writeDefaultCtor, writeDescription, writeHTMLContents, writeMessageImports, writeSectionName, writeStandardCommentID, writeXHTMLFooter, writeXHTMLFooter, writeXHTMLHeader, writeXHTMLHeader

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.sandev.sandbuild.SandGenerator

cleanup, generate

Constructor Detail

ProtocolBufferGenerator

public ProtocolBufferGenerator()

Method Detail

getFileSpec

protected java.lang.String getFileSpec(java.io.File baseDir)
                                throws org.sandev.sandbuild.SandGeneratorException

Return lastApp/src/TLD/domain/appname/util/PBMsgs.proto for the triggering build. The given baseDir is ignored.

Overrides:

getFileSpec in class AggregateGeneratorBase

Throws:

org.sandev.sandbuild.SandGeneratorException

writeFile

protected void writeFile(java.io.PrintStream out,
                         org.sandev.sandbuild.SandDecl[] decls)

Write the proto declarations source file.

Overrides:

writeFile in class AggregateGeneratorBase

writeMessageDecls

protected void writeMessageDecls(java.io.PrintStream out,
                                 org.sandev.sandbuild.SandDecl[] decls)

Write the declarations for each of the defined structs.

writeBaseTypes

protected void writeBaseTypes(java.io.PrintStream out)

Write the message declarations for the basic types we require.

hasContainedInterfaces

protected boolean hasContainedInterfaces(com.sun.javadoc.FieldDoc[] fields,
                                         org.sandev.sandbuild.SandDecl[] decls,
                                         com.sun.javadoc.ClassDoc cd)

Return true if the given fields include interfaces. A class with interface fields can't be serialized using protocol buffers.

writeMessageDecl

protected void writeMessageDecl(java.io.PrintStream out,
                                java.lang.String className,
                                com.sun.javadoc.ClassDoc cd,
                                com.sun.javadoc.FieldDoc[] fields)

Write a struct message declaration

getProtoType

protected java.lang.String getProtoType(java.lang.String typename)

Return the protobuf type for the given SAND type.

writeReceiverDecls

protected void writeReceiverDecls(java.io.PrintStream out,
                                  org.sandev.sandbuild.SandDecl[] decls)