io.inversion

Class Collection

java.lang.Object

io.inversion.Rule<Collection>

io.inversion.Collection

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<Collection>

public class Collection
extends Rule<Collection>
implements java.io.Serializable

Represents a REST Collection and maps JSON properties property names and logical cross Collection data relationships to underlying Db tables and column names.

Api users interact with Collections and their JSON representation while Inversion abstracts the details of of the storage implementations.

Collections can remap ugly legacy column names to pretty JSON friendly camelCase names, and Collection Relationships can be used to create logical traversable foreign keys between Collections with the same underlying Db or even between Collections with different backend storage systems.

Generally it is the job of a Db to reflect on its underlying data source and automatically configure Collections and the associated Relationships that will be accessed and manipulated by Api caller.

The Engine inspects the inbound Request path and attempts to match a Collection to the call.

The default mapping would be: /${endpointPath}/[${collection}]/[${resource}]/[${relationship}]

Querying "/${endpointPath}/${collection}" would typically result an a paginated list of resources ie. rows from your underlying Db translated into JSON speak.

Querying "/${endpointPath}/${collection}/${resource}" will fetch a single resource or row.

Querying "/${endpointPath}/${collection}/${resource}/${relationship}" will fetch all members from the relationship target Collection that are related to resource.

RestGet/Post/Put/Patch/DeleteAction are responsible for handling basic Rest semantics for interacting with Dbs via Collections.

TODO: check on test cases related to hasName and path matching TODO: need tests for resource keys with commas

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class io.inversion.Rule

Rule.RuleMatcher

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Set<java.lang.String>	aliases Additional names that should cause this Collection to match to a Request.
protected Db	db The backend storage adapter that probably generated this Collection and associated Indexes and Relationships.
protected boolean	exclude Set this to true to prevent it from being automatically exposed through your Api.
protected java.util.ArrayList<Index>	indexes Representation of underlying Db datasource indexes.
protected java.util.ArrayList<Property>	properties Properties map database column names to JSON property names.
protected java.util.ArrayList<Relationship>	relationships Relationships like resources in one collection to the resources in another collection.
protected java.lang.String	tableName The backend datasource name that this Collection operates on.

Fields inherited from class io.inversion.Rule

configMap, configStr, excludeMatchers, excludeOn, includeMatchers, includeOn, log, name, order

Constructor Summary

Constructors

Constructor and Description
Collection()
Collection(java.lang.String defaultName)

Method Summary

Modifier and Type	Method and Description
Collection	copy() Performs a deep clone operation via object serialization/deserialization.
Rows.Row	decodeResourceKey(Index index, java.lang.String inKey) Decodes a resource key into its columnName / value parts.
Rows.Row	decodeResourceKey(java.lang.String inKey) Decodes a resource key into its columnName / value parts.
Rows	decodeResourceKeys(Index index, java.lang.String inKeys) Decodes a comma separated list of encoded resource keys.
Rows	decodeResourceKeys(java.lang.String inKeys)
static java.lang.String	decodeStr(java.lang.String string) The reciprocal of encodeStr(String) that replaces "\@[0-9a-f]{4}" hex sequences with the unescaped oritional unescaped character.
static java.lang.String	encodeResourceKey(java.util.List pieces) Creates a "~" separated url safe concatenation of pieces
java.lang.String	encodeResourceKey(java.util.Map<java.lang.String,java.lang.Object> values) Encodes the potentially multiple values of a resources primary index into a url path safe single value.
static java.lang.String	encodeResourceKey(java.util.Map values, Index index) Encodes the potentially multiple values of an index into a url path and query string safe single value.
static java.lang.String	encodeStr(java.lang.String string) Encodes non url safe characters into a friendly "@FOUR_DIGIT_HEX_VALUE" equivalent that itself will not be modified by URLEncoder.encode(String).
boolean	equals(java.lang.Object object)
Property	findProperty(java.lang.String jsonOrColumnName) Finds the property with case insensitive jsonOrColumnName.
java.util.Set<java.lang.String>	getAliases()
java.lang.String	getColumnName(java.lang.String jsonName)
Db	getDb()
protected Rule.RuleMatcher	getDefaultIncludeMatch() Designed to allow subclasses to provide a default match behavior of no configuration was provided by the developer.
Index	getIndex(java.lang.String indexName) Gets an index by case insensitive name.
Index	getIndexByType(java.lang.String indexType)
java.util.ArrayList<Index>	getIndexes()
java.lang.String	getName()
Index	getPrimaryIndex() Finds the first unique Index with the fewest number of Properties.
java.util.List<Property>	getProperties()
Property	getProperty(java.lang.String jsonOrColumnName) Convenience overload of findProperty(String).
Property	getPropertyByColumnName(java.lang.String columnName) Find the property with case insensitive columnName
Property	getPropertyByJsonName(java.lang.String jsonName) Find the property with case insensitive jsonName
Relationship	getRelationship(java.lang.String name)
java.util.List<Relationship>	getRelationships()
java.lang.String	getTableName()
boolean	hasName(java.lang.String nameOrAlias)
boolean	isExclude()
boolean	isLinkTbl() Returns true if all columns are foreign keys.
static void	main(java.lang.String[] args)
void	removeIndex(Index index)
void	removeProperty(Property prop)
void	removeRelationship(Relationship relationship)
Collection	withAliases(java.lang.String... aliases)
Collection	withDb(Db db)
Collection	withExclude(boolean exclude)
Collection	withIndex(java.lang.String name, java.lang.String type, boolean unique, java.lang.String... propertyNames) Fluent utility method for constructing and adding a new Index.
Collection	withIndexes(Index... indexes)
Collection	withManyToOneRelationship(Collection parentCollection, java.lang.String childPropertyName, Property... childFkProps) Fluent utility method to construct a Relationship and associated Indexes.
Collection	withManyToOneRelationship(Collection parentCollection, java.lang.String childPropertyName, java.lang.String... childFkProps) Fluent utility method to construct a Relationship and associated Indexes.
Collection	withOneToManyRelationship(java.lang.String parentPropertyName, Collection childCollection, java.lang.String childPropertyName, Property... childFkProps) Fluent utility method to construct a Relationship and associated Indexes.
Collection	withOneToManyRelationship(java.lang.String parentPropertyName, Collection childCollection, java.lang.String childPropertyName, java.lang.String... childFkProps) Fluent utility method to construct a Relationship and associated Indexes.
Collection	withProperties(Property... props) Adds the property definitions to this Collection.
Collection	withProperty(java.lang.String name, java.lang.String type) Fluent utility method for constructing a new Property and adding it to the Collection.
Collection	withProperty(java.lang.String name, java.lang.String type, boolean nullable) Fluent utility method for constructing a new Property and adding it to the Collection.
Collection	withRelationship(Relationship relationship) Add a new Relationship if a Relationship with the same name does not already exist.
Collection	withRelationships(Relationship... relationships)
Collection	withTableName(java.lang.String name)

Methods inherited from class io.inversion.Rule

checkLazyConfig, compareTo, doLazyConfig, getAllExcludePaths, getAllIncludePaths, getConfig, getConfig, getConfigKeys, getExcludeMatchers, getIncludeMatchers, getOrder, match, matches, matches, toString, withConfig, withExcludeOn, withExcludeOn, withExcludeOn, withIncludeOn, withIncludeOn, withIncludeOn, withName, withOrder

Methods inherited from class java.lang.Object

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

Field Detail

aliases

protected final java.util.Set<java.lang.String> aliases

Additional names that should cause this Collection to match to a Request.

For example, in an e-commerce environment, you may overload the "orders" collection with aliases "cart", "basket", and "bag".

properties

protected final java.util.ArrayList<Property> properties

Properties map database column names to JSON property names.

indexes

protected final java.util.ArrayList<Index> indexes

Representation of underlying Db datasource indexes.

relationships

protected final java.util.ArrayList<Relationship> relationships

Relationships like resources in one collection to the resources in another collection.

db

protected transient Db db

The backend storage adapter that probably generated this Collection and associated Indexes and Relationships.

tableName

protected java.lang.String tableName

The backend datasource name that this Collection operates on.

The tableName might be "ORDER_DETAIL" but the Collection might be named "orderDetails".

exclude

protected boolean exclude

Set this to true to prevent it from being automatically exposed through your Api.

Constructor Detail

Collection

public Collection()

Collection

public Collection(java.lang.String defaultName)

Method Detail

encodeResourceKey

public static java.lang.String encodeResourceKey(java.util.Map values,
                                                 Index index)

Encodes the potentially multiple values of an index into a url path and query string safe single value.

In a typical REST Api configuration where you url paths might map to something like "${endpoint}/${collection}/[${resource}][?{querystring}]", ${resource} is the primary index of the resource that has been encoded here.

That might look like "/bookstore/books/12345" or in the case of a compound primary index It might look like "/bookstore/orders/4567~abcde" where the "~" character is used to separate parts of the key.

The names of the index fields are not encoded, only the values, relying on index property order to remain consistent.

This methods is used by various actions when constructing hypermedia urls that allow you to uniquely identify individual resources (records in a Db) or to traverse Relationships.

The inverse of this method is decodeResourceKeys(Index, String) which is used to decode inbound Url path and query params to determine which resource is being referenced.

Parameters:

values - column name to Property value mapping for a resource

index - the index identifying the values that should be encoded

Returns:

a url safe encoding of the index values separated by "~" characters or null if any of the values for an index key is null.

See Also:

encodeStr(String), decodeResourceKeys(Index, String)

encodeResourceKey

public static java.lang.String encodeResourceKey(java.util.List pieces)

Creates a "~" separated url safe concatenation of pieces

Parameters:

pieces - key parts to be encoded

Returns:

a url safe encoding of the pieces separated by "~" characters

See Also:

encodeStr(String), encodeResourceKey(Map, Index)

main

public static void main(java.lang.String[] args)

encodeStr

public static java.lang.String encodeStr(java.lang.String string)

Encodes non url safe characters into a friendly "@FOUR_DIGIT_HEX_VALUE" equivalent that itself will not be modified by URLEncoder.encode(String).

For example, encodeing "abcd/efg" would result in "abcd@002fefg" where "@002f" is the hex encoding for "/".

While "~" characters are considered url safe, the are specifically included for encoding so that decodeResourceKeys(Index, String) can split a value on "~" before decoding its parts.

Parameters:

string - the string to encode

Returns:

a url safe string with non safe characters encoded as '@FOUR_DIGIT_HEX_VALUE'

See Also:

Safe characters for friendly urls, encodeResourceKey(Map, Index), decodeResourceKeys(Index, String), decodeStr(String)

decodeStr

public static java.lang.String decodeStr(java.lang.String string)

The reciprocal of encodeStr(String) that replaces "\@[0-9a-f]{4}" hex sequences with the unescaped oritional unescaped character.

Parameters:

string - the string to decode

Returns:

a string with characters escaped to their hex equivalent replaced with the unescaped value.

See Also:

encodeResourceKey(Map, Index), decodeResourceKeys(Index, String), encodeStr(String)

getDefaultIncludeMatch

protected Rule.RuleMatcher getDefaultIncludeMatch()

Description copied from class: Rule

Designed to allow subclasses to provide a default match behavior of no configuration was provided by the developer.

Overrides:

getDefaultIncludeMatch in class Rule<Collection>

Returns:

the default collection match rule: "{_collection:" + getName() + "}/[:_resource]/[:_relationship]/*"

See Also:

Request.COLLECTION_KEY, Request.RESOURCE_KEY, Request.RELATIONSHIP_KEY

isLinkTbl

public boolean isLinkTbl()

Returns true if all columns are foreign keys.

In an RDBMS system, this would indicate that the table is used to link both sides of a many-to-many relationship and it should NOT be a public REST Collection.

Returns:

the true if all columns are foreign keys.

getProperty

public Property getProperty(java.lang.String jsonOrColumnName)

Convenience overload of findProperty(String).

Parameters:

jsonOrColumnName - the property to get

Returns:

the Property with a case insensitive json name or column name match.

See Also:

findProperty(String)

findProperty

public Property findProperty(java.lang.String jsonOrColumnName)

Finds the property with case insensitive jsonOrColumnName.

The algo tries to find a matching json property name first before relooping over the props looking of a column name match.

Parameters:

jsonOrColumnName - the property to find

Returns:

the Property with a case insensitive json name or column name match.

getPropertyByJsonName

public Property getPropertyByJsonName(java.lang.String jsonName)

Find the property with case insensitive jsonName

Parameters:

jsonName - the name of the property to get

Returns:

the property with jsonName

getPropertyByColumnName

public Property getPropertyByColumnName(java.lang.String columnName)

Find the property with case insensitive columnName

Parameters:

columnName - the name of the property to get

Returns:

the property with columnName

getColumnName

public java.lang.String getColumnName(java.lang.String jsonName)

equals

public boolean equals(java.lang.Object object)

Overrides:

equals in class java.lang.Object

Returns:

true if object has the same Db and name as this Collection

getDb

public Db getDb()

Returns:

the underlying Db

withDb

public Collection withDb(Db db)

Parameters:

db - the db to set

Returns:

this

getTableName

public java.lang.String getTableName()

Returns:

the tableName backing this Collection in the Db.

withTableName

public Collection withTableName(java.lang.String name)

Parameters:

name - the name to set

Returns:

this

getName

public java.lang.String getName()

Overrides:

getName in class Rule<Collection>

Returns:

the name of the Collection defaulting to tableName if name is null.

getProperties

public java.util.List<Property> getProperties()

Returns:

a shallow copy of properties

withProperties

public Collection withProperties(Property... props)

Adds the property definitions to this Collection.

If there is an existing prop with a json name to json name match or a column name to column name match, the new prop will not be added as it conflicts with the existing one.

Parameters:

props - the properties to add

Returns:

this

withProperty

public Collection withProperty(java.lang.String name,
                               java.lang.String type)

Fluent utility method for constructing a new Property and adding it to the Collection.

Parameters:

name - the name of the Property to add

type - the type of the Property to add

Returns:

this

See Also:

Property.Property(String, String, boolean)

withProperty

public Collection withProperty(java.lang.String name,
                               java.lang.String type,
                               boolean nullable)

Fluent utility method for constructing a new Property and adding it to the Collection.

Parameters:

name - the name of the Property to add

type - the type of the Property to add

nullable - is the Property nullable

Returns:

this

See Also:

Property.Property(String, String, boolean)

removeProperty

public void removeProperty(Property prop)

getPrimaryIndex

public Index getPrimaryIndex()

Finds the first unique Index with the fewest number of Properties.

Returns:

the Index that should be treated as the primary key for the Collection

See Also:

Index.isUnique()

getIndexByType

public Index getIndexByType(java.lang.String indexType)

Parameters:

indexType - the case insensative index type identifier

Returns:

the first index with type = indexType

getIndex

public Index getIndex(java.lang.String indexName)

Gets an index by case insensitive name.

Parameters:

indexName - the name of the Index to get

Returns:

the requested Index

getIndexes

public java.util.ArrayList<Index> getIndexes()

Returns:

a shallow copy of indexes

withIndexes

public Collection withIndexes(Index... indexes)

withIndex

public Collection withIndex(java.lang.String name,
                            java.lang.String type,
                            boolean unique,
                            java.lang.String... propertyNames)

Fluent utility method for constructing and adding a new Index.

If an Index with name exists it will be updated with the new information.

All of the Properties in propertyNames must already exist.

Parameters:

name - the name of the Index to create/add

type - the type of the Index to create/add

unique - specifics if Index to create/add is unique

propertyNames - the Properties that make up the index

Returns:

this

See Also:

Index.Index(String, String, boolean, Property...)

removeIndex

public void removeIndex(Index index)

isExclude

public boolean isExclude()

withExclude

public Collection withExclude(boolean exclude)

getRelationship

public Relationship getRelationship(java.lang.String name)

Parameters:

name - the name of the Relationship to get

Returns:

the Relationship with a case insensitve name match

getRelationships

public java.util.List<Relationship> getRelationships()

Returns:

a shallow copy of relationships.

removeRelationship

public void removeRelationship(Relationship relationship)

withRelationships

public Collection withRelationships(Relationship... relationships)

Parameters:

relationships - the relationships to set

Returns:

this

withRelationship

public Collection withRelationship(Relationship relationship)

Add a new Relationship if a Relationship with the same name does not already exist.

Parameters:

relationship - the Relationship to add

Returns:

this

withManyToOneRelationship

public Collection withManyToOneRelationship(Collection parentCollection,
                                            java.lang.String childPropertyName,
                                            java.lang.String... childFkProps)

Fluent utility method to construct a Relationship and associated Indexes.

Parameters:

parentCollection - the parent collection of the relationship being created

childPropertyName - name of the json property that will hold this relationship reference

childFkProps - names of the existing Properties that make up the foreign key

Returns:

this

See Also:

withManyToOneRelationship(Collection, String, Property...)

withManyToOneRelationship

public Collection withManyToOneRelationship(Collection parentCollection,
                                            java.lang.String childPropertyName,
                                            Property... childFkProps)

Fluent utility method to construct a Relationship and associated Indexes.

In addition to the new Relationship a new foreign key Index will be created from childFkProps to parentCollection's primary Index.

Parameters:

parentCollection - the related parent Collection

childPropertyName - what to call this relationship in the json representation of this Collection's resources.

childFkProps - the Collections Properties that make up the foreign key

Returns:

this

withOneToManyRelationship

public Collection withOneToManyRelationship(java.lang.String parentPropertyName,
                                            Collection childCollection,
                                            java.lang.String childPropertyName,
                                            java.lang.String... childFkProps)

Fluent utility method to construct a Relationship and associated Indexes.

This is a convenience overload of withOneToManyRelationship(String, Collection, String, Property...) to be used when code wiring Apis and you don't want to lookup references to the actual Property objects.

Parameters:

parentPropertyName - the name of the json property for the parent that references the child

childCollection - the target child collection

childPropertyName - the name of hte json property for the child that references the parent

childFkProps - names of the existing Properties that make up the foreign key

Returns:

this

See Also:

withOneToManyRelationship(String, Collection, String, Property...)

withOneToManyRelationship

public Collection withOneToManyRelationship(java.lang.String parentPropertyName,
                                            Collection childCollection,
                                            java.lang.String childPropertyName,
                                            Property... childFkProps)

Fluent utility method to construct a Relationship and associated Indexes.

In addition to the new Relationship a new foreign key Index will be created from childFkProps to this Collection's primary Index.

Parameters:

parentPropertyName - the name of the json property for the parent that references the child

childCollection - the target child collection

childPropertyName - the name of hte json property for the child that references the parent

childFkProps - Properties that make up the foreign key

Returns:

this

hasName

public boolean hasName(java.lang.String nameOrAlias)

Parameters:

nameOrAlias - the name or alias to check for

Returns:

true if the name or aliases match

getAliases

public java.util.Set<java.lang.String> getAliases()

Returns:

a shallow clone of aliases

withAliases

public Collection withAliases(java.lang.String... aliases)

encodeResourceKey

public java.lang.String encodeResourceKey(java.util.Map<java.lang.String,java.lang.Object> values)

Encodes the potentially multiple values of a resources primary index into a url path safe single value.

Parameters:

values - the key value pairs to encode

Returns:

a url safe encoding of the resources primary index values

See Also:

encodeResourceKey(Map, Index)

decodeResourceKey

public Rows.Row decodeResourceKey(java.lang.String inKey)

Decodes a resource key into its columnName / value parts.

Parameters:

inKey - the resource key to decode

Returns:

the decoded columnName / value pairs.

See Also:

decodeResourceKeys(Index, String), encodeResourceKey(Map, Index)

decodeResourceKeys

public Rows decodeResourceKeys(java.lang.String inKeys)

decodeResourceKey

public Rows.Row decodeResourceKey(Index index,
                                  java.lang.String inKey)

Decodes a resource key into its columnName / value parts.

Parameters:

index - identifies the columnNames by position

inKey - the encoded string to decode

Returns:

the decoded columnName / value pairs.

See Also:

decodeResourceKeys(Index, String), encodeResourceKey(Map, Index)

decodeResourceKeys

public Rows decodeResourceKeys(Index index,
                               java.lang.String inKeys)

Decodes a comma separated list of encoded resource keys.

Parameters:

index - identifies the columnNames to decode

inKeys - a comma separated list of encoded resource keys

Returns:

a list of decoded columnName value pairs

See Also:

encodeResourceKey(Map, Index), encodeStr(String), decodeStr(String)

copy

public Collection copy()

Performs a deep clone operation via object serialization/deserialization.

It is useful when you want to manually wire up numerous copies of a collection but tweak each one a bit differently.

For example, if you were connecting to a DynamoDb or CosmosDb where a single table is overloaded to support different domain objects.

This feature requires Collection, Relationship and Index to be Serializable.

The Db reference here is transient and reconnected to the clone so that this instance and the copy reference the same Db.

Returns:

a deep copy of this Collection referencing the same underlying Db instance.