io.inversion

Class Db<T extends Db>

java.lang.Object

io.inversion.Db<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, Map), 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 static 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)

Method Summary

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	castDbOutput(Property property, java.lang.Object value) Casts value as Property.type
java.lang.Object	castJsonInput(Property property, java.lang.Object value) Casts value as Property.type.
java.lang.Object	castJsonInput(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>> records) Upserts the key/values pairs for each record 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<java.lang.String,java.lang.Object>	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 collection, Relationship relationship) Attempts to construct a sensible json property name for a Relationship.
java.util.Map<java.lang.String,java.lang.Object>	mapTo(java.util.Map<java.lang.String,java.lang.Object> 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>> records) 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... collections)
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

reservedParams

protected static final 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

log

protected final org.slf4j.Logger log

collections

protected final 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 final 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.

includeColumns

protected final 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 final 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)

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.

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 - the api to start

Returns:

this

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.

Parameters:

api - the api to start

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

Parameters:

api - the api shutting down

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 - the collection being queried

params - RQL terms that have been translated to use Property jsonNames

Returns:

A list of maps with keys as Property jsonNames

Throws:

ApiException - TODO: update/correct this javadoc

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 - the collection to query

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<java.lang.String,java.lang.Object> getKey(Collection collection,
                                                               java.lang.Object node)

mapTo

public java.util.Map<java.lang.String,java.lang.Object> mapTo(java.util.Map<java.lang.String,java.lang.Object> 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>> records)
                                                   throws ApiException

Upserts the key/values pairs for each record 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 record 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 - the collection being modified

records - the records being modified

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>> records)
                                       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 - the collection to patch

records - the key/value pairs to update on existing records

Returns:

the keys of all resources modified

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:

collection - the collection being modified

indexValues - the identifiers for the records to delete

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 - when configuration fails

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 - the name of an underlying datasource table to be turned into a pretty REST collection name

Returns:

a camelCased and pluralized 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:

JSON property name

makeRelationshipName

protected java.lang.String makeRelationshipName(Collection collection,
                                                Relationship relationship)

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:

collection - the collection the relationship name being created will belong to

relationship - the relationship

Returns:

the json property name representing this Relationship.

castDbOutput

public java.lang.Object castDbOutput(Property property,
                                     java.lang.Object value)

Casts value as Property.type

Parameters:

property - the property the value is assigned to

value - the value pulled from the DB

Returns:

value cast to Property.type

See Also:

Utils.castDbOutput(String, Object)

castJsonInput

public java.lang.Object castJsonInput(Property property,
                                      java.lang.Object value)

Casts value as Property.type.

Parameters:

property - the property the value is assigned to

value - the value to cast to the datatype of property

Returns:

value cast to Property.type

See Also:

Utils.castJsonInput(String, Object)

castJsonInput

public java.lang.Object castJsonInput(java.lang.String type,
                                      java.lang.Object value)

Casts value to as type.

Parameters:

type - the type to cast to

value - the value to cast

Returns:

value cast to type

See Also:

Utils.castJsonInput(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.

Parameters:

includeTables - underlying data source tables that should be included as REST collections

Returns:

this

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... collections)

Parameters:

collections - to include (add not replace)

Returns:

this

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 - the collection in question

name - the name of the property to optionally filter

Returns:

true if the property should be excluded

withIncludeColumns

public T withIncludeColumns(java.lang.String... columnNames)

withExcludeColumns

public T withExcludeColumns(java.lang.String... columnNames)

getName

public java.lang.String getName()

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

Returns:

this

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)