java fc.jdbc.dbobjects.Generate -conf <path-to-configuration-file>

Command line tool to generate java objects/framework corresponding to the
specified database and catalog. The configuration file must contain the
following properties in standard java property file format (note all
parameter names are case sensitive):

If a table or column name uses a Java language reserved keywords (such as
naming a column name "public", "switch", etc.), this tool will fail
immediately. This is the best option because it would be very hard to
carry on properly/partially by ignoring columns/tables that use reserved
keywords. Fixing the DB is the only sane option in this scenario. (And, of
course, you can always manually exclude the offending table via the
exclude list as defined below).

============= Required =========================
jdbc.url
jdbc.driver
jdbc.user   
jdbc.password   
    the above 4 properties have the usual JDBC meanings and
    must be specified (don't default to anything)

jdbc.catalog        
    if not specified, uses the default catalog

log.level
    a fc.io.SystemLog.Level; this will set the logging level
    used by this application. The value specified here is
    case insensitive. Defaults to the default SystemLog
    logging level.

target.dbname
    the name of the target database. This must be one
    of the names specified in the fc.jdbc.DBName class.
    Usually this is optional since we can elucidate the
    name of the db from the jdbc driver. For some reason,
    in case we cannot a runtime-message will be displayed 
    and this value will then have to be filled in.

target.types_to_process
    list of table types to process. By default all
    types are processed but a comma delimted list
    here can be listed from those returned by
    java.sql.DatabaseMetaData.getTableTypes()
    Note, the database is free to return more types
    than mentioned in the javadoc for this method.
    postgres for example also returns: index, sequence

target.tables_to_process
    comma delimited list of case-insensitive table names to
    process. Typically a list of tables will be provided
    along with an accompanying package name for these tables,
    this way a subset of all tables available in the current
    database catalog will be generated for the specified
    package. 
    
    A * can be used as either or both a suffix and prefix and has 
    the effect of matching everything at that point. So 
    *foo matches all tables ending with foo and *foo* matches
    all tables containing the name foo

    Defaults to all tables if not specified.
    
target.tables_to_ignore
    comma delimited list of case-insensitive table names
    to ignore (and not process). Any tables defined here 
    (if any) are ignored and not generated. 
    
    A * can be used as either or both a suffix and prefix and has 
    the effect of matching everything at that point. So 
    *foo matches all tables ending with foo and *foo* matches
    all tables containing the name foo

    Defaults to an empty list which means no tables will be ignored
    additionally by this parameter.

    The process/ignore sequence is:
    -- choose any tables specified by target.tables_to_process
      (default all tables in the database)
    -- then, from the list of tables to process, prune any tables
      that are specified by target.tables_to_ignore
      (default empty, so nothing is pruned)
    -- generate the resulting set of tables here.

dbspecific.mysql.boolean_hack
    converts TINYINT types to boolean. See javadoc for
    Generate for more information. Defaults to true
    
generate.output.dir 
    full path to directory where output files will be
    written. Will create this directory if necessary. Full
    paths are preferred, relative paths are typically (but
    may not always) resolved relative to the directory from
    where the jvm was launched
    
-------------------------------------------------------
The following proprties affect the name of the generated
class and get/set accessor methods. We want the class and
method names to mirror table and attribute names. However,
sometimes JDBC drivers and/or databases may return names
differenly than defined in that database. For example, if a
table was named in sentence case (say FooBar), the returned
name may be foobar (all lowercase). Typically, we want to
just use the returned name as-is but options here can change
the default settings. 
---------------------------------------------------------

generate.wrangle.sentence.delimiter
    Used by the "sentence" option while name wrangling
    Defaults to underscore _ if not specified
    

generate.wrangle.classname  
    Affects the generated classname. One of: 
    none, lower, upper, sentence, firstup 
    
    Defaults to none if not specified

    none: 
        generated class name from table name as-is
    upper:  
        generated class name is all upper case table name
    lower:  
        generated class name is all lower case table name
    sentence: 
        the first letter of each word in the table name is
        capitalized where a word is seperated by the word
        delimiter. The word delimiter is specified by the
        "generate.wrangle.sentence.delimiter" property.
    firstup: 
        converts only the first letter of the table name to
        upper case
    
Example:

|TableName ||  none   | upper | lower  |sentence|firstup|
|==========||=========|=======|========|========|=======|
| fooBar   || fooBar  |FOOBAR | foobar | FooBar |Foobar |
|__________||_________|_______|________|________|_______|
| foo_bar  || foo_bar |FOO_BAR| foo_bar| FooBar |Foo_bar|    
|__________||_________|_______|________|________|_______|
    

generate.wrangle.methodname 
    Affects the generated accessor method names. One of: 
    none, none_under, lower, upper, sentence, firstup, underscore 
    
    Defaults to none_under if not specified

    none: 
        generated method name from table attribute name is as-is
    none_under:
        generated method name from table attribute name is as-is
        and seperated by get/set via an underscore, for example,
        foo becomes get_foo()
    upper:  
        generated method name is all upper case attribute name
    lower:  
        generated method name is all lower case attribute name
    sentence: 
        the first letter of each word in the method name
        is capitalized where a word is seperated by the word
        delimiter. The word delimiter is specified by the
        "generate.name_wrangling.word.delimiter" property.
    firstup: 
        converts only the first letter of the method name
        to upper case

Example:
       
|Column ||  none  |none_under| upper  | lower  |sentence|firstup |
|=======||========|==========|========|========|========|========|
|fBar   ||getfBar |get_fBar  |getFBAR |getfbar |getFbar |getFbar |
|_______||________|__________|________|________|________|________|
|f_bar  ||getf_bar|get_f_bar |getF_BAR|getf_bar|getFBar |getF_bar|
|_______||________|__________|________|________|________|________|


generate.class_package
    package name for generated classes. Defaults to none.

generate.class_vis
    visibility of generated classes, get/set methods and
    utility methods. Defaults to "public"
        
generate.field_vis
    visibility of generated fields. Defaults to "private"
    if accessors (get/set) will be generated, otherwise 
    defaults to "public"

generate.accessors
    if true, get/set methods for each field are generated.
    Defaults to true.  

generate.nullIfNullableUnknown
    if set to true, will mark a column as nullable if
    the jdbc driver does not know if that column is actually
    nullable or not. (i.e, the nullability information for
    that column is unknown). Defaults to false.

generate.booleanObjectForNullableBooleans
    if set to true, if a boolean column is nullable in the database, 
    will map that column to a java Boolean (as opposed to a primitive
    boolean). 
    
    if false, all boolean columns are mapped to primitive java
    booleans (regardless of nullability in the database). This can be 
    tricky since in JDBC, a null boolean value in the db translates to a 
    false when using primitive booleans).
        
    Defaults to true. 
    
    Note: when using mysql boolean hack, only primitive booleans are 
    generated, regardless of what is set in this option.
 
generate.modifiableAutoIncrementColumns
    control whether auto_increment columns will be allowed to be modified
    via setter accessor methods. By default this is false which implies
    that set() methods will NOT be generated for auto increment columns.
    Note: get() methods will always be generated, this only controls the
    set() method generation and the default setting here is almost always
    appropriate.
    
    Be very careful when setting to true. Your application may break in random
    ways. If this is true, when you create a new DBO and if you set values
    in it from scratch and those values include serial/auto-inc columns, you
    must save that object as:
    
    a) using fooMgr.update() *if* that manually set serial value 
       already exists in the database 
    b) or, fooMgr.save() if that serial value does not exist in the 
       database.
    
generate.preparedstatement.setxxx.length_param
    sets the third ("length") parameter that certain set
    methods in PreparedStatements need. From the JDBC spec:
        
    ------------------- quote ------------------------
    setBinaryStream for streams containing uninterpreted
    bytes, setAsciiStream for streams containing ASCII
    characters, and setUnicodeStream for streams containing
    Unicode characters. These methods take one more argument
    than the other setXXX methods because the total length
    of the stream must be specified. This is necessary
    because some databases need to know the total transfer
    size before any data is sent.
    -------------------- end --------------------------
    
    Options are: available, intmax 
    
    available:  passes stream.available() as the length param
    intmax:     passes Integer.MAX_SIZE as the length param
                (theoretically, that should be ok since 
                the driver should stop reading the stream
                if EOF is encountered before MAX_SIZE bytes).
    
    Defaults to: available

dbspecific.postgres.getObjectToString
    getObject is used to retrieve columns where a more specific type is not known. For
    example, Type.OTHER returned for a column by the postgres driver for JSON types.
    
    The object returned is implementation specific (PGobject for postgres). We can
    get the value contained - in the object returned by get_bar() for example - by 
    either:
    
        ((PGobject) foo.get_bar()).getValue()
        -or- 
        foo.get_bar().toString()
    
    Both return the String-ified value. 
    
    The latter toString() form is simple but have to remember to do this everytime. 
    Ideally speaking, we would *like* to say (using org.json.JSONObject in this example):
    
        JSONObject json = new JSONObject(foo.get_bar())
        
    This however, will add all the *other* crap in PGobject to our JSON. We really have
    to say:
    
        JSONObject json = new JSONObject(foo.get_bar().toString())

    So this defaults to true, to save the hassle. Setting it to false will return the PGobject 
    (or whatever the driver returns) instead.
    

