Db (inversion-api 0.9.11.1 API)

java.lang.Object
- io.inversion.Db<T>

Type Parameters:

T -
```
public abstract class Db<T extends Db>
extends java.lang.Object
```
An adapter to an underlying data source.
The goal of the Db abstraction is to allow Actions like RestGet/Put/Post/Patch/DeleteAction to apply the same REST CRUD operations agnostically across multiple backend data storage engines.
The primary job of a Db subclass is to:
1. reflectively generate Collections to represent their underlying tables (or buckets, folders, containers etc.) columns, indexes, and relationships, during #doStartup(Api).
2. implement REST CRUD support by implementing #select(Collection, List), upsert(Collection, List), delete(Collection, List).
Actions such as DbGetAction then:
1. translate a REST collection/resource request into columnName based json and RQL,
2. execute the requested CRUD method on the Collection's underlying Db
3. then translate the results back from the Db columnName based data into the approperiate jsonName version for external consumption.

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`bootstrap` Indicates that this Db should reflectively create and configure Collections to represent its underlying tables.
`protected java.util.ArrayList<Collection>`	`collections` The Collections that are the REST interface to the backend tables (or buckets, folders, containers etc.) this Db exposes through an Api.
`protected boolean`	`dryRun` When set to true the Db will do everything it can to "work offline" logging commands it would have run but not actually running them.
`protected Path`	`endpointPath` Used to differentiate which Collection is being referred by a Request when an Api supports Collections with the same name from different Dbs.
`protected java.util.Set<java.lang.String>`	`excludeColumns` OPTIONAL column names that should be excluded from RQL queries, upserts and patches.
`protected java.util.Set<java.lang.String>`	`includeColumns` OPTIONAL column names that should be included in RQL queries, upserts and patches.
`protected java.util.Map<java.lang.String,java.lang.String>`	`includeTables` A tableName to collectionName map that can be used by whitelist backend tables that should be included in reflicitive Collection creation.
`protected org.slf4j.Logger`	`log`
`protected java.lang.String`	`name` The name of his Db used for "name.property" style autowiring.
`protected java.util.Set<java.lang.String>`	`reservedParams` These params are specifically NOT passed to the Query for parsing.
`protected java.lang.String`	`type` A property that can be used to disambiguate different backends supported by a single subclass.

Constructor Summary

Constructors
Constructor and Description

Db()

Db(java.lang.String name)

Constructors
Constructor and Description
`Db()`
`Db(java.lang.String name)`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected java.lang.String`	`beautifyCollectionName(java.lang.String tableName)` Attempts to camelCase and pluralize the table name to make it an attractive REST collection name.
`protected java.lang.String`	`beautifyName(java.lang.String name)` Try to make an attractive camelCase valid javascript variable name.
`protected void`	`buildCollections()` Creates a collection for every table name in `includeTables` giving the Collections and Properties beautified JSON names.
`protected void`	`buildRelationships()` Creates ONE_TO_MANY, MANY_TO_ONE, and MANY_TO_MANY Relationships with attractive RESTish names based on the primary Index and foreign key Index structures of the Collections.
`java.lang.Object`	`cast(Property property, java.lang.Object value)` Casts value as Property.type.
`java.lang.Object`	`cast(java.lang.String type, java.lang.Object value)` Casts value to as type.
`protected void`	`configApi(Api api)` Adds all non excluded Collections to the Api via Api.withCollection
`protected void`	`configDb()` Subclasses should reflectively create Collections and Properties, Indexes, and Relationships here.
`abstract void`	`delete(Collection collection, java.util.List<java.util.Map<java.lang.String,java.lang.Object>> indexValues)` Deletes rows identified by the unique index values from the underlying data source.
`void`	`doPatch(Collection collection, java.util.List<java.util.Map<java.lang.String,java.lang.Object>> rows)`
`abstract Results`	`doSelect(Collection collection, java.util.List<Term> queryTerms)` Finds all records that match the supplied RQL query terms.
`protected void`	`doShutdown()`
`protected void`	`doShutdown(Api api)` Made to be overridden by subclasses or anonymous inner classes to do specific cleanup
`protected void`	`doStartup(Api api)` Made to be overridden by subclasses or anonymous inner classes to do specific init of an Api.
`abstract java.util.List<java.lang.String>`	`doUpsert(Collection collection, java.util.List<java.util.Map<java.lang.String,java.lang.Object>> rows)` Upserts the key/values pairs for each row into the underlying data source.
`boolean`	`filterOutJsonProperty(Collection collection, java.lang.String name)` Checks if "collectionName.columnName" or just "columnName" is specifically included or excluded via `includeColumns` `excludeColumns` or is a valid Property columnName.
`Collection`	`getCollectionByTableName(java.lang.String tableName)`
`java.util.List<Collection>`	`getCollections()`
`Path`	`getEndpointPath()`
`java.lang.String`	`getHref(java.lang.Object hrefOrNode)`
`java.util.Map`	`getKey(Collection collection, java.lang.Object node)`
`java.lang.String`	`getName()`
`protected Property`	`getProperty(java.lang.String tableName, java.lang.String columnName)`
`java.lang.String`	`getType()`
`boolean`	`isBootstrap()`
`boolean`	`isDryRun()`
`boolean`	`isRunning(Api api)`
`boolean`	`isType(java.lang.String... types)`
`protected java.lang.String`	`makeRelationshipName(Collection resource, Relationship rel)` Attempts to construct a sensible json property name for a Relationship.
`java.util.Map`	`mapTo(java.util.Map srcRow, Index srcCols, Index destCols)`
`protected java.util.Set<Term>`	`mapToColumnNames(Collection collection, Term term)`
`protected void`	`mapToJsonNames(Collection collection, Term term)`
`java.util.List<java.lang.String>`	`patch(Collection collection, java.util.List<java.util.Map<java.lang.String,java.lang.Object>> nodes)` Should be called by Actions instead of upsert() only when all records are strictly known to exist.
`void`	`removeCollection(Collection table)`
`Results`	`select(Collection collection, java.util.Map<java.lang.String,java.lang.String> params)` Finds all records that match the supplied RQL query terms.
`T`	`shutdown()` Shutsdown all running Apis.
`T`	`shutdown(Api api)`
`T`	`startup(Api api)` Called by an Api to as part of Api.startup().
`java.util.List<java.lang.String>`	`upsert(Collection collection, java.util.List<java.util.Map<java.lang.String,java.lang.Object>> rows)`
`T`	`withBootstrap(boolean bootstrap)`
`T`	`withCollection(Collection collection)`
`T`	`withCollections(Collection... colls)`
`T`	`withDryRun(boolean dryRun)`
`T`	`withEndpointPath(Path endpointPath)`
`T`	`withExcludeColumns(java.lang.String... columnNames)`
`T`	`withIncludeColumns(java.lang.String... columnNames)`
`T`	`withIncludeTable(java.lang.String tableName, java.lang.String collectionName)` Whitelists tableName as an underlying table that should be reflectively bootstrapped and exposed as collectionName.
`T`	`withIncludeTables(java.lang.String includeTables)` Utility that parses a comma and pipe separated list of table name to collection name mappings.
`T`	`withName(java.lang.String name)` The name of the Db is used primarily for autowiring "name.property" bean props from
`T`	`withType(java.lang.String type)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - log
```
protected final org.slf4j.Logger log
```
  - collections
```
protected java.util.ArrayList<Collection> collections
```
    The Collections that are the REST interface to the backend tables (or buckets, folders, containers etc.) this Db exposes through an Api.
  - includeTables
```
protected java.util.Map<java.lang.String,java.lang.String> includeTables
```
    A tableName to collectionName map that can be used by whitelist backend tables that should be included in reflicitive Collection creation.
  - bootstrap
```
protected boolean bootstrap
```
    Indicates that this Db should reflectively create and configure Collections to represent its underlying tables.
    This would be false when an Api designer wants to very specifically configure an Api probably when the underlying db does not support the type of reflection required. For example, you may want to put specific Property and Relationship structure on top of an unstructured JSON document store.
  - name
```
protected java.lang.String name
```
    The name of his Db used for "name.property" style autowiring.
  - type
```
protected java.lang.String type
```
    A property that can be used to disambiguate different backends supported by a single subclass.
    For example type might be "mysql" for a JdbcDb.
  - endpointPath
```
protected Path endpointPath
```
    Used to differentiate which Collection is being referred by a Request when an Api supports Collections with the same name from different Dbs.
  - includeColumns
```
protected java.util.Set<java.lang.String> includeColumns
```
    OPTIONAL column names that should be included in RQL queries, upserts and patches.
    
    See Also:
    
    filterOutJsonProperty(Collection, String)
  - excludeColumns
```
protected java.util.Set<java.lang.String> excludeColumns
```
    OPTIONAL column names that should be excluded from RQL queries, upserts and patches.
    
    See Also:
    
    filterOutJsonProperty(Collection, String)
  - reservedParams
```
protected java.util.Set<java.lang.String> reservedParams
```
    These params are specifically NOT passed to the Query for parsing. These are either dirty worlds like sql injection tokens or the are used by actions themselves
  - dryRun
```
protected boolean dryRun
```
    When set to true the Db will do everything it can to "work offline" logging commands it would have run but not actually running them.
- Constructor Detail
  - Db
```
public Db()
```
  - Db
```
public Db(java.lang.String name)
```
- Method Detail
  - startup
```
public final T startup(Api api)
```
    Called by an Api to as part of Api.startup().
    This implementation really only manages starting/started state, with the heaving lifting of bootstrapping delegated to doStartup(Api).
    
    Parameters:
    
    api -
    
    Returns:
    
    See Also:
    
    doStartup(Api)
  - doStartup
```
protected void doStartup(Api api)
```
    Made to be overridden by subclasses or anonymous inner classes to do specific init of an Api.
    This method will not be called a second time after for an Api unless the Api is shutdown and then restarted.
    The default implementation, when isBootstrap() is true, calls configDb() once globally and configApi(Api) once for each Api passed in.
    
    See Also:
    
    configDb(), configApi(Api)
  - shutdown
```
public T shutdown()
```
    Shutsdown all running Apis.
    This is primarily a method used for testing.
    
    Returns:
    
    this
  - doShutdown
```
protected void doShutdown()
```
  - shutdown
```
public T shutdown(Api api)
```
  - doShutdown
```
protected void doShutdown(Api api)
```
    Made to be overridden by subclasses or anonymous inner classes to do specific cleanup
  - isRunning
```
public boolean isRunning(Api api)
```
  - select
```
public final Results select(Collection collection,
                            java.util.Map<java.lang.String,java.lang.String> params)
                     throws ApiException
```
    Finds all records that match the supplied RQL query terms.
    The implementation of this method primarily translates jsonNames to columnNames for RQL inputs and JSON outputs delegating the work to doSelect(Collection, List) where all ins and outs are based on columnName.
    
    Parameters:
    
    collection -
    
    queryTerms - RQL terms that have been translated to use Property jsonNames
    
    Returns:
    
    A list of maps with keys as Property jsonNames
    
    Throws:
    
    ApiException
  - doSelect
```
public abstract Results doSelect(Collection collection,
                                 java.util.List<Term> queryTerms)
                          throws ApiException
```
    Finds all records that match the supplied RQL query terms.
    
    Parameters:
    
    collection -
    
    queryTerms - RQL terms that have been translated to use Property columnNames not jsonNames
    
    Returns:
    
    A list of maps with keys as Property columnNames not jsonNames
    
    Throws:
    
    ApiException
  - upsert
```
public final java.util.List<java.lang.String> upsert(Collection collection,
                                                     java.util.List<java.util.Map<java.lang.String,java.lang.Object>> rows)
                                              throws ApiException
```
    Throws:
    
    ApiException
  - getHref
```
public java.lang.String getHref(java.lang.Object hrefOrNode)
```
  - getKey
```
public java.util.Map getKey(Collection collection,
                            java.lang.Object node)
```
  - mapTo
```
public java.util.Map mapTo(java.util.Map srcRow,
                           Index srcCols,
                           Index destCols)
```
  - doUpsert
```
public abstract java.util.List<java.lang.String> doUpsert(Collection collection,
                                                          java.util.List<java.util.Map<java.lang.String,java.lang.Object>> rows)
                                                   throws ApiException
```
    Upserts the key/values pairs for each row into the underlying data source.
    Keys that are not supplied in the call but that exist in the row in the target DB should not be modified.
    Each row should minimally contain key value pairs that satisfy one of the tables unique index constraints allowing an update to take place instead of an insert if the row already exists in the underlying data source.
    IMPORTANT #1 - implementors should note that the keys on each row in rows may be different.
    IMPORTANT #2 - strict POST/PUT vs POST/PATCH semantics are implementation specific. For example, a RDBMS backed implementation may choose to upsert only the supplied client supplied keys effectively making this a POST/PATCH operation. A document store that is simply storing the supplied JSON may not be able to do partial updates elegantly and replace existing documents entirely rendering this a POST/PUT.
    
    Parameters:
    
    collection -
    
    rows -
    
    Returns:
    
    the encoded resource key for every supplied row
    
    Throws:
    
    ApiException
  - patch
```
public java.util.List<java.lang.String> patch(Collection collection,
                                              java.util.List<java.util.Map<java.lang.String,java.lang.Object>> nodes)
                                       throws ApiException
```
    Should be called by Actions instead of upsert() only when all records are strictly known to exist.
    The default implementation simply calls upsert().
    
    Parameters:
    
    collection -
    
    rows - the key/value pairs to update on existing records
    
    Throws:
    
    ApiException
  - doPatch
```
public void doPatch(Collection collection,
                    java.util.List<java.util.Map<java.lang.String,java.lang.Object>> rows)
             throws ApiException
```
    Throws:
    
    ApiException
  - delete
```
public abstract void delete(Collection collection,
                            java.util.List<java.util.Map<java.lang.String,java.lang.Object>> indexValues)
                     throws ApiException
```
    Deletes rows identified by the unique index values from the underlying data source.
    IMPORTANT implementors should note that the keys on each indexValues row may be different.
    The keys should have come from a unique index, meaning that the key/value pairs for each row should uniquely identify the row, however there is no guarantee that each row will reference the same index.
    
    Parameters:
    
    table -
    
    indexValues -
    
    Throws:
    
    ApiException
  - configApi
```
protected void configApi(Api api)
```
    Adds all non excluded Collections to the Api via Api.withCollection
    
    Parameters:
    
    api - the Api to configure.
  - configDb
```
protected void configDb()
                 throws ApiException
```
    Subclasses should reflectively create Collections and Properties, Indexes, and Relationships here.
    The default implementation simply delegates to buildCollections() and buildRelationships().
    Generally, you will need to override buildCollections when implementing a new Db subclass but can probably leave buildRelationships alone as all it does is reflectively build Relationships off of Indexes that are on the Collections.
    
    Throws:
    
    ApiException
  - buildCollections
```
protected void buildCollections()
```
    Creates a collection for every table name in includeTables giving the Collections and Properties beautified JSON names.
    Subclasses should override this method to reflectively create Collections, Properties and Indexes and then call super.buildCollections() if they want names them beautified.
  - buildRelationships
```
protected void buildRelationships()
```
    Creates ONE_TO_MANY, MANY_TO_ONE, and MANY_TO_MANY Relationships with attractive RESTish names based on the primary Index and foreign key Index structures of the Collections.
    For all foreign key indexes, two relationships objects are created representing both sides of the relationship. A MANY_TO_ONE also creates a ONE_TO_MANY and vice versa and there are always two for a MANY_TO_MANY modeling the relationship from both sides.
  - beautifyCollectionName
```
protected java.lang.String beautifyCollectionName(java.lang.String tableName)
```
    Attempts to camelCase and pluralize the table name to make it an attractive REST collection name.
    
    Parameters:
    
    tableName -
    
    Returns:
    
    a camelCased and pluralied version of tableName
    
    See Also:
    
    beautifyName(String)
  - beautifyName
```
protected java.lang.String beautifyName(java.lang.String name)
```
    Try to make an attractive camelCase valid javascript variable name.
    Lots of sql db designers use things like SNAKE_CASE_COLUMN_NAMES that look terrible as json property names.
    
    Parameters:
    
    name - the to beautify
    
    Returns:
    
    a camelCased version of name
    
    See Also:
    
    https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Variables
  - makeRelationshipName
```
protected java.lang.String makeRelationshipName(Collection resource,
                                                Relationship rel)
```
    Attempts to construct a sensible json property name for a Relationship.
    For example, a "ONE Author TO_MANY Books" relationship might show up as "books" on the Author collection and "Author" on the Books collection.
    The algorithm attempts to pluralize the "MANY" side of the relationship.
    The "ONE" side of a relationship uses the first foreign key column name minus an trailing case insensitive "ID", so in the above example, if there is a foreign key Book.authorId pointing to the Author table, the the name would be "author". If the foreign key column name was Book.primaryAuthorKey, the relationship would be named "primaryAuthorKey".
    
    Parameters:
    
    resource -
    
    rel -
    
    Returns:
    
    the json property name for this Relationship.
  - cast
```
public java.lang.Object cast(Property property,
                             java.lang.Object value)
```
    Casts value as Property.type.
    
    Parameters:
    
    property -
    
    value -
    
    Returns:
    
    value cast to Property.type
    
    See Also:
    
    io.inversion.utils.Utils.cast(String, Object)
  - cast
```
public java.lang.Object cast(java.lang.String type,
                             java.lang.Object value)
```
    Casts value to as type.
    
    Parameters:
    
    type -
    
    value -
    
    Returns:
    
    value cast to type
    
    See Also:
    
    io.inversion.utils.Utils.cast(String, Object)
  - mapToJsonNames
```
protected void mapToJsonNames(Collection collection,
                              Term term)
```
  - mapToColumnNames
```
protected java.util.Set<Term> mapToColumnNames(Collection collection,
                                               Term term)
```
  - getProperty
```
protected Property getProperty(java.lang.String tableName,
                               java.lang.String columnName)
```
  - getCollectionByTableName
```
public Collection getCollectionByTableName(java.lang.String tableName)
```
  - removeCollection
```
public void removeCollection(Collection table)
```
  - getCollections
```
public java.util.List<Collection> getCollections()
```
    Returns:
    
    a shallow copy of collections
  - withIncludeTables
```
public T withIncludeTables(java.lang.String includeTables)
```
    Utility that parses a comma and pipe separated list of table name to collection name mappings.
    Example: db.tables=customers,books-prod-catalog|books,INVENTORY_ADJUSTED_BY_PERIOD|inventory
    This method is primarily useful when an Api designer wants to manually configure Collections instead of having the Db reflectively build the Collections.
    This method can also be called prior to the db reflection phase of startup to whitelist tables that the reflection should include.
    The string is first split on "," to get a list of table names.
    If the table name contains a "|" character, the part on the left is considered the tableName and the part on the right is considered the collectionName.
    If there is no "|" then the beautified tableName is used for the collectionName.
    
    See Also:
    
    beautifyCollectionName(String)
  - withIncludeTable
```
public T withIncludeTable(java.lang.String tableName,
                          java.lang.String collectionName)
```
    Whitelists tableName as an underlying table that should be reflectively bootstrapped and exposed as collectionName.
    
    Parameters:
    
    tableName - the table to build a Collection for
    
    collectionName - the name of the target collection that can be different from tableName.
    
    Returns:
    
    this
  - withCollections
```
public T withCollections(Collection... colls)
```
    Parameters:
    
    collections - to include (add not replace)
  - withCollection
```
public T withCollection(Collection collection)
```
  - filterOutJsonProperty
```
public boolean filterOutJsonProperty(Collection collection,
                                     java.lang.String name)
```
    Checks if "collectionName.columnName" or just "columnName" is specifically included or excluded via includeColumns excludeColumns or is a valid Property columnName.
    This can be used to filter out things like URL path mapped parameters that don't actually match to "columns" in a document store.
    This does not prevent the underlying Property from being part of a Collection object model and the names here don't actually have to be Properties.
    
    Parameters:
    
    collection -
    
    columnName -
    
    Returns:
  - withIncludeColumns
```
public T withIncludeColumns(java.lang.String... columnNames)
```
  - withExcludeColumns
```
public T withExcludeColumns(java.lang.String... columnNames)
```
  - getName
```
public java.lang.String getName()
```
    Returns:
    
    the name
  - withName
```
public T withName(java.lang.String name)
```
    The name of the Db is used primarily for autowiring "name.property" bean props from
    
    Parameters:
    
    name - the name to set
  - isType
```
public boolean isType(java.lang.String... types)
```
  - getType
```
public java.lang.String getType()
```
  - withType
```
public T withType(java.lang.String type)
```
  - isBootstrap
```
public boolean isBootstrap()
```
  - withBootstrap
```
public T withBootstrap(boolean bootstrap)
```
  - getEndpointPath
```
public Path getEndpointPath()
```
  - withEndpointPath
```
public T withEndpointPath(Path endpointPath)
```
  - isDryRun
```
public boolean isDryRun()
```
  - withDryRun
```
public T withDryRun(boolean dryRun)
```

Class Db<T extends Db>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

log

collections

includeTables

bootstrap

name

type

endpointPath

includeColumns

excludeColumns

reservedParams

dryRun

Constructor Detail

Db

Db

Method Detail

startup

doStartup

shutdown

doShutdown

shutdown

doShutdown

isRunning

select

doSelect

upsert

getHref

getKey

mapTo

doUpsert

patch

doPatch

delete

configApi

configDb

buildCollections

buildRelationships

beautifyCollectionName

beautifyName

makeRelationshipName

cast

cast

mapToJsonNames

mapToColumnNames

getProperty

getCollectionByTableName

removeCollection

getCollections

withIncludeTables

withIncludeTable

withCollections

withCollection

filterOutJsonProperty

withIncludeColumns

withExcludeColumns

getName

withName

isType

getType

withType

isBootstrap

withBootstrap

getEndpointPath

withEndpointPath

isDryRun

withDryRun