org.sandev.generator
Class SQLSchemaVerifierGenerator

java.lang.Object
  org.sandev.generator.GeneratorCommon
      org.sandev.generator.AggregateGeneratorBase
          org.sandev.generator.AggregateMappedGeneratorBase
              org.sandev.generator.SQLSchemaVerifierGenerator

All Implemented Interfaces:

org.sandev.sandbuild.SandGenerator

public class SQLSchemaVerifierGenerator

extends AggregateMappedGeneratorBase

implements org.sandev.sandbuild.SandGenerator

Write table verification code to make sure the struct definitions we are working with match what is in the database.

Foreign keys are a significant barrier to bad data. If your database will be accessed by any other applications, or data will be archived, then foreign keys should be declared. For development purposes you can get by without them, but it's always good to work with the more restrictive scenario.

A reference can always be null. It is up to the application logic to enforce anything different. A reference may never be dangling (you can't have a reference to something that doesn't exist).

Non-nullable foreign keys are used for two purposes:

1. enforcing that the elements of a reference array are not left pointing at something that doesn't exist.
2. enforcing that MyStructB, which inherits from MyStructA, doesn't suddenly and permanently morph into a MyStructA due to someone removing just the MyStructB table row.

Field Summary

Fields inherited from class org.sandev.generator.AggregateMappedGeneratorBase

structmap, structPrefix

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

SQLSchemaVerifierGenerator()

Method Summary

void	cleanupSecondaryFiles(org.sandev.sandbuild.SandDecl[] decls, java.io.File baseDir) Clean up the schema SQL file.
protected com.sun.javadoc.ClassDoc	findClassDocForName(java.lang.String name, com.sun.javadoc.ClassDoc[] classes) Return the ClassDoc corresponding to the reference name.
static com.sun.javadoc.ClassDoc[]	getAbstractPersistentStructs(org.sandev.sandbuild.SandDecl[] decls) Return the abstract persistent ClassDocs out of these struct decls.
static com.sun.javadoc.FieldDoc[]	getCoreTableFields(com.sun.javadoc.ClassDoc cd) Return the fields for this table.
protected java.lang.String	getFileSpec(java.io.File baseDir) Return "gen_base/src/org/sandev/tools/JDBC/pre_SchemaVerifier.java" or the equivalent filespec for the given platform.
protected java.lang.String	getNullSemantics(com.sun.javadoc.FieldDoc fd) Return whether this field may be null or not.
static com.sun.javadoc.ClassDoc[]	getPersistentStructs(org.sandev.sandbuild.SandDecl[] decls) Return the persistent ClassDocs out of these struct declarations.
static boolean	isValidJDBCType(java.lang.String type) Determine whether a string is the name of a JDBC Type Constant.
protected java.lang.String	sqlTypeBaseDecl(java.lang.String type) Given a mapped value type, return the unqualified base type as defined in java.sql.Types
protected void	writeCtor(java.io.PrintStream out)
protected void	writeFieldVerifier(java.io.PrintStream out, java.lang.String mappedFieldName, java.lang.String mappedFieldType, com.sun.javadoc.FieldDoc fd) Write field verification code.
protected void	writeFile(java.io.PrintStream out, org.sandev.sandbuild.SandDecl[] decls) Write the SchemaVerifier source file
protected void	writePostamble(java.io.PrintStream out)
protected void	writePreamble(java.io.PrintStream out, org.sandev.sandbuild.SandDecl[] decls)
protected void	writeRelationCreationSQL(java.io.PrintStream out, java.lang.String reltable, java.lang.String parentFieldName, java.lang.String parentFieldType, java.lang.String childFieldName, java.lang.String childFieldType, java.lang.String indexFieldName, java.lang.String indexFieldType, com.sun.javadoc.ClassDoc ownercd, com.sun.javadoc.ClassDoc refcd, com.sun.javadoc.FieldDoc fduid, java.lang.String linePrefix, java.lang.String lineSuffix) Write out the array relation statement.
protected void	writeRelationSQL(java.io.PrintStream out, com.sun.javadoc.ClassDoc cd, com.sun.javadoc.FieldDoc fd, com.sun.javadoc.ClassDoc[] classes, com.sun.javadoc.FieldDoc[] fields)
protected void	writeRelationVerifierMethods(java.io.PrintStream out, com.sun.javadoc.ClassDoc cd, com.sun.javadoc.ClassDoc[] classes, com.sun.javadoc.FieldDoc fd, com.sun.javadoc.FieldDoc[] fields)
void	writeSecondaryFiles(org.sandev.sandbuild.SandDecl[] decls, java.io.File baseDir, java.util.Collection dirtyFiles) Write the schema SQL file.
protected void	writeTableBrokenFieldsMethod(java.io.PrintStream out, com.sun.javadoc.ClassDoc cd, com.sun.javadoc.FieldDoc[] fields)
void	writeTableCreationSQL(java.io.PrintStream out, java.lang.String tablename, com.sun.javadoc.ClassDoc cd, com.sun.javadoc.FieldDoc[] fields, com.sun.javadoc.ClassDoc[] classes, java.lang.String linePrefix, java.lang.String lineSuffix, boolean includeForeignKeyDecls) Write out the table creation statement.
protected void	writeTableVerifierMethod(java.io.PrintStream out, java.lang.String tablename)
protected void	writeTableVerifierMethods(java.io.PrintStream out, com.sun.javadoc.ClassDoc cd, com.sun.javadoc.ClassDoc[] classes)
protected void	writeUtilMethods(java.io.PrintStream out)
protected void	writeVerifyTables(java.io.PrintStream out, org.sandev.sandbuild.SandDecl[] decls)

Methods inherited from class org.sandev.generator.AggregateMappedGeneratorBase

getMappedFieldName, getMappedFieldRelation, getMappedFieldRelationChild, getMappedFieldRelationIndex, getMappedFieldRelationParent, getMappedFieldType, getMappedStructName, loadStructMapper, loadStructMapper

Methods inherited from class org.sandev.generator.AggregateGeneratorBase

addSandAttrValToDecls, cleanup, generate, getExtra, setExtra

Methods inherited from class org.sandev.generator.GeneratorCommon

capitalize, copyfile, deletefile, filterHTMLLine, getDeclaredFields, getFields, getInheritanceHierarchy, getLastAppProject, getLastUtilDir, getLongInstanceName, getPrintStream, getSandProject, getShortInstanceName, getUtilPackage, getVisibleFields, 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

SQLSchemaVerifierGenerator

public SQLSchemaVerifierGenerator()

Method Detail

getFileSpec

protected java.lang.String getFileSpec(java.io.File baseDir)

Return "gen_base/src/org/sandev/tools/JDBC/pre_SchemaVerifier.java" or the equivalent filespec for the given platform.

writeFile

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

Write the SchemaVerifier source file

Throws:

org.sandev.sandbuild.SandGeneratorException

writeSecondaryFiles

public void writeSecondaryFiles(org.sandev.sandbuild.SandDecl[] decls,
                                java.io.File baseDir,
                                java.util.Collection dirtyFiles)
                         throws org.sandev.sandbuild.SandGeneratorException

Write the schema SQL file.

Throws:

org.sandev.sandbuild.SandGeneratorException

writeRelationSQL

protected void writeRelationSQL(java.io.PrintStream out,
                                com.sun.javadoc.ClassDoc cd,
                                com.sun.javadoc.FieldDoc fd,
                                com.sun.javadoc.ClassDoc[] classes,
                                com.sun.javadoc.FieldDoc[] fields)

cleanupSecondaryFiles

public void cleanupSecondaryFiles(org.sandev.sandbuild.SandDecl[] decls,
                                  java.io.File baseDir)
                           throws org.sandev.sandbuild.SandGeneratorException

Clean up the schema SQL file.

Throws:

org.sandev.sandbuild.SandGeneratorException

writePreamble

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

writePostamble

protected void writePostamble(java.io.PrintStream out)

writeCtor

protected void writeCtor(java.io.PrintStream out)

writeVerifyTables

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

writeTableVerifierMethods

protected void writeTableVerifierMethods(java.io.PrintStream out,
                                         com.sun.javadoc.ClassDoc cd,
                                         com.sun.javadoc.ClassDoc[] classes)

writeTableCreationSQL

public void writeTableCreationSQL(java.io.PrintStream out,
                                  java.lang.String tablename,
                                  com.sun.javadoc.ClassDoc cd,
                                  com.sun.javadoc.FieldDoc[] fields,
                                  com.sun.javadoc.ClassDoc[] classes,
                                  java.lang.String linePrefix,
                                  java.lang.String lineSuffix,
                                  boolean includeForeignKeyDecls)

Write out the table creation statement. Each line of output is wrapped in the linePrefix and lineSuffix so this can be used for various code generation purposes.

writeRelationVerifierMethods

protected void writeRelationVerifierMethods(java.io.PrintStream out,
                                            com.sun.javadoc.ClassDoc cd,
                                            com.sun.javadoc.ClassDoc[] classes,
                                            com.sun.javadoc.FieldDoc fd,
                                            com.sun.javadoc.FieldDoc[] fields)

writeFieldVerifier

protected void writeFieldVerifier(java.io.PrintStream out,
                                  java.lang.String mappedFieldName,
                                  java.lang.String mappedFieldType,
                                  com.sun.javadoc.FieldDoc fd)

Write field verification code. Each JDBC driver reports database metadata slightly differently, so several checks are required for each field.

• If the StructMapper mapped the field to a valid JDBC type, checks the expected type against the type reported by the database.
• If that check fails, or if the StructMapper didn't map to a JDBC type, compares the type name reported by the database with the expected type name.
• If the field is a Java String, performs a second name comparison ignoring any column length in the column name.
• If the field is a Java String, checks column length.

writeRelationCreationSQL

protected void writeRelationCreationSQL(java.io.PrintStream out,
                                        java.lang.String reltable,
                                        java.lang.String parentFieldName,
                                        java.lang.String parentFieldType,
                                        java.lang.String childFieldName,
                                        java.lang.String childFieldType,
                                        java.lang.String indexFieldName,
                                        java.lang.String indexFieldType,
                                        com.sun.javadoc.ClassDoc ownercd,
                                        com.sun.javadoc.ClassDoc refcd,
                                        com.sun.javadoc.FieldDoc fduid,
                                        java.lang.String linePrefix,
                                        java.lang.String lineSuffix)

Write out the array relation statement. Each line of output is wrapped in the linePrefix and lineSuffix so this can be used for various code generation purposes.

notes on FOREIGN KEY checking:

• If you have a DBA to manage your database, they will likely manage the table creation process themselves, rather than letting this generated code do it. The table checking only verifies the column names, not foreign keys, so it doesn't care either way. So it's up to the DBA if they want the foreign key constraints in there or not.
• If you are using a higher-end database, you will probably use the database backup/restore capabilities rather than the apps/basics DataImportExport processing. That means that you could have the foreign keys on, because you are not going to be loading instances out of order from application code.
• The DataImportExport processing cannot use the SQL 92 standard "SET CONSTRAINTS DEFERRED" call within an import transaction because this is not supported across all databases. Most databases support a global switch to accomplish batch loading (for example HSQL has "SET REFERENTIAL_INTEGRITY TRUE"), but these switch calls don't seem to be standardized.
• Although it's not clear exactly how much overhead foreign key checking adds to the update processing, it is not zero. Given that
  1. most deployment scenarios are not going to be modifying these relations manually
  2. we can trust the add/update/delete code to do the right thing since it is all autogenerated
  it would seem we can safely skip this overhead.

writeTableVerifierMethod

protected void writeTableVerifierMethod(java.io.PrintStream out,
                                        java.lang.String tablename)

writeTableBrokenFieldsMethod

protected void writeTableBrokenFieldsMethod(java.io.PrintStream out,
                                            com.sun.javadoc.ClassDoc cd,
                                            com.sun.javadoc.FieldDoc[] fields)

writeUtilMethods

protected void writeUtilMethods(java.io.PrintStream out)

getPersistentStructs

public static com.sun.javadoc.ClassDoc[] getPersistentStructs(org.sandev.sandbuild.SandDecl[] decls)

Return the persistent ClassDocs out of these struct declarations.

getAbstractPersistentStructs

public static com.sun.javadoc.ClassDoc[] getAbstractPersistentStructs(org.sandev.sandbuild.SandDecl[] decls)

Return the abstract persistent ClassDocs out of these struct decls.

getCoreTableFields

public static com.sun.javadoc.FieldDoc[] getCoreTableFields(com.sun.javadoc.ClassDoc cd)

Return the fields for this table. This is a standard field retrieval call except:

1. we only inherit fields if our parent is declared abstract
2. if we are extending another struct, we filter out all the synthetic field except uniqueID, since they are represented in the parent table
3. reference array fields are removed

getNullSemantics

protected java.lang.String getNullSemantics(com.sun.javadoc.FieldDoc fd)

Return whether this field may be null or not. The following may be null:

• A String value
• A Date value
• A reference to another object

Other declarations (int, long, double) may not be null. The default and invalid values are declared for each field. The value for the field is stored directly, changes to defaults are handled as part of data management over time. See Persist.html in the top level docs for details.

An array of references is stored as a separate relation. An array of references may not contain null entries. It can be empty but not null.

These same null value semantics are also used in update and query processing. If you override these semantics be sure to override the associated processing methods also.

findClassDocForName

protected com.sun.javadoc.ClassDoc findClassDocForName(java.lang.String name,
                                                       com.sun.javadoc.ClassDoc[] classes)

Return the ClassDoc corresponding to the reference name.

sqlTypeBaseDecl

protected java.lang.String sqlTypeBaseDecl(java.lang.String type)

Given a mapped value type, return the unqualified base type as defined in java.sql.Types

isValidJDBCType

public static boolean isValidJDBCType(java.lang.String type)

Determine whether a string is the name of a JDBC Type Constant.