public class Collection extends Rule<Collection> implements java.io.Serializable
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
Rule.RuleMatcher| 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.lang.String |
pluralDisplayName |
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 |
schemaRef
A reference to an externa OpenAPI schema that will be used in OpenAPI/documentation generation.
|
protected java.lang.String |
singularDisplayName |
protected java.lang.String |
tableName
The backend datasource name that this Collection operates on.
|
ALL_METHODS, configMap, description, excludeMatchers, excludeOn, includeMatchers, includeOn, log, name, order, params| Constructor and Description |
|---|
Collection() |
Collection(java.lang.String defaultName) |
| Modifier and Type | Method and Description |
|---|---|
Collection |
copy()
Performs a deep clone operation via object serialization/deserialization.
|
java.util.Map<java.lang.String,java.lang.Object> |
decodeKey(Index index,
java.lang.String key,
boolean useJsonPropertyNames)
Decodes a resource key.
|
java.util.Map<java.lang.String,java.lang.Object> |
decodeKeyToColumnNames(Index index,
java.lang.String inKey)
Decodes a resource key into its columnName / value parts.
|
java.util.Map<java.lang.String,java.lang.Object> |
decodeKeyToJsonNames(java.lang.String inKeys)
Decodes a resource key into its columnName / value parts.
|
static java.lang.String |
encodeKey(java.util.List pieces)
Creates a "~" separated url safe concatenation of
pieces |
static java.lang.String |
encodeKey(java.util.Map<java.lang.String,java.lang.Object> values,
Index index,
boolean useJsonPropertyNames)
Encodes the potentially multiple values of an index into a url path and query string safe single value.
|
java.lang.String |
encodeKeyFromColumnNames(java.util.Map<java.lang.String,java.lang.Object> values)
Encodes the resourceKey from the values using column names from the primary index.
|
java.lang.String |
encodeKeyFromJsonNames(java.util.Map<java.lang.String,java.lang.Object> values)
Encodes the resourceKey from the values using json names from the primary index.
|
java.lang.String |
encodeKeyFromJsonNames(java.util.Map<java.lang.String,java.lang.Object> values,
Index index) |
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 java.util.List<Rule.RuleMatcher> |
getDefaultIncludeMatchers()
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() |
java.lang.String |
getPluralDisplayName() |
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() |
Index |
getResourceIndex()
Finds best index to be used to uniquely identify the resource.
|
java.lang.String |
getSchemaRef() |
java.lang.String |
getSingularDisplayName() |
java.lang.String |
getTableName() |
boolean |
hasName(java.lang.String nameOrAlias) |
boolean |
isExclude() |
boolean |
isLinkTbl()
Returns true if all columns are foreign keys.
|
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 |
withForeignKey(Collection related,
java.lang.String... myProperties) |
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(java.lang.String thisCollectionsRelationshipJsonPropertyName,
Collection parentCollection,
java.lang.String... thisCollectionsForeignKeyProps)
Fluent utility method to construct a Relationship and associated Indexes.
|
Collection |
withOneToManyRelationship(java.lang.String thisCollectionsRelationshipJsonPropertyName,
Collection childCollection,
java.lang.String... childCollectionsForeignKeyProps)
Fluent utility method to construct a Relationship and associated Indexes.
|
Collection |
withPluralDisplayName(java.lang.String pluralName) |
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 |
withSchemaRef(java.lang.String schemaRef) |
Collection |
withSingularDispalyName(java.lang.String singularName) |
Collection |
withTableName(java.lang.String name) |
afterWiringComplete, checkLazyConfig, compareTo, doLazyConfig, getAllExcludePaths, getAllIncludeMethods, getAllIncludePaths, getDescription, getExcludeMatchers, getIncludeMatchers, getOrder, getParams, match, match, matches, matches, toString, withDescription, withExcludeOn, withExcludeOn, withIncludeOn, withIncludeOn, withName, withOrder, withParam, withParamsprotected final java.util.Set<java.lang.String> aliases
For example, in an e-commerce environment, you may overload the "orders" collection with aliases "cart", "basket", and "bag".
protected final java.util.ArrayList<Property> properties
protected final java.util.ArrayList<Index> indexes
protected final java.util.ArrayList<Relationship> relationships
protected transient Db db
protected java.lang.String tableName
The tableName might be "ORDER_DETAIL" but the Collection might be named "orderDetails".
protected java.lang.String pluralDisplayName
protected java.lang.String singularDisplayName
protected java.lang.String schemaRef
protected boolean exclude
public Collection()
public Collection(java.lang.String defaultName)
protected java.util.List<Rule.RuleMatcher> getDefaultIncludeMatchers()
RulegetDefaultIncludeMatchers in class Rule<Collection>Request.COLLECTION_KEY,
Request.RESOURCE_KEY,
Request.RELATIONSHIP_KEYpublic boolean isLinkTbl()
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.
public Property getProperty(java.lang.String jsonOrColumnName)
findProperty(String).jsonOrColumnName - the property to getfindProperty(String)public Property findProperty(java.lang.String jsonOrColumnName)
The algo tries to find a matching json property name first before relooping over the props looking of a column name match.
jsonOrColumnName - the property to findpublic Property getPropertyByJsonName(java.lang.String jsonName)
jsonName - the name of the property to getjsonNamepublic Property getPropertyByColumnName(java.lang.String columnName)
columnName - the name of the property to getcolumnNamepublic java.lang.String getColumnName(java.lang.String jsonName)
public boolean equals(java.lang.Object object)
equals in class java.lang.Objectobject has the same Db and name as this Collectionpublic Db getDb()
public Collection withDb(Db db)
db - the db to setpublic java.lang.String getTableName()
public Collection withTableName(java.lang.String name)
name - the name to setpublic java.lang.String getName()
getName in class Rule<Collection>tableName if name is null.public Collection withSingularDispalyName(java.lang.String singularName)
public java.lang.String getSingularDisplayName()
public Collection withPluralDisplayName(java.lang.String pluralName)
public java.lang.String getPluralDisplayName()
public java.util.List<Property> getProperties()
propertiespublic Collection withProperties(Property... props)
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.
props - the properties to addpublic Collection withProperty(java.lang.String name, java.lang.String type)
name - the name of the Property to addtype - the type of the Property to addProperty.Property(String, String, boolean)public Collection withProperty(java.lang.String name, java.lang.String type, boolean nullable)
name - the name of the Property to addtype - the type of the Property to addnullable - is the Property nullableProperty.Property(String, String, boolean)public void removeProperty(Property prop)
public Index getResourceIndex()
Index.isUnique()public Index getIndexByType(java.lang.String indexType)
indexType - the case insensative index type identifierpublic Index getIndex(java.lang.String indexName)
indexName - the name of the Index to getpublic java.util.ArrayList<Index> getIndexes()
indexespublic Collection withIndexes(Index... indexes)
public Collection withIndex(java.lang.String name, java.lang.String type, boolean unique, java.lang.String... propertyNames)
If an Index with name exists it will be updated with the new information.
All of the Properties in propertyNames must already exist.
name - the name of the Index to create/addtype - the type of the Index to create/addunique - specifics if Index to create/add is uniquepropertyNames - the Properties that make up the indexIndex.Index(String, String, boolean, Property...)public Collection withForeignKey(Collection related, java.lang.String... myProperties)
public void removeIndex(Index index)
public boolean isExclude()
public Collection withExclude(boolean exclude)
public Relationship getRelationship(java.lang.String name)
name - the name of the Relationship to getpublic java.util.List<Relationship> getRelationships()
relationships.public void removeRelationship(Relationship relationship)
public Collection withRelationships(Relationship... relationships)
relationships - the relationships to setpublic Collection withRelationship(Relationship relationship)
relationship - the Relationship to addpublic Collection withManyToOneRelationship(java.lang.String thisCollectionsRelationshipJsonPropertyName, Collection parentCollection, java.lang.String... thisCollectionsForeignKeyProps)
In addition to the new Relationship a new foreign key Index will be created from childFkProps
to parentCollection's primary Index.
thisCollectionsRelationshipJsonPropertyName - what to call this relationship in the json representation of this Collection's resources.parentCollection - the related parent CollectionthisCollectionsForeignKeyProps - the Collections Properties that make up the foreign keypublic Collection withOneToManyRelationship(java.lang.String thisCollectionsRelationshipJsonPropertyName, Collection childCollection, java.lang.String... childCollectionsForeignKeyProps)
In addition to the new Relationship a new foreign key Index will be created from childFkProps
to this Collection's primary Index.
thisCollectionsRelationshipJsonPropertyName - the name of the json property for the parent that references the childchildCollection - the target child collectionchildCollectionsForeignKeyProps - Properties that make up the foreign keypublic boolean hasName(java.lang.String nameOrAlias)
nameOrAlias - the name or alias to check forpublic java.util.Set<java.lang.String> getAliases()
aliasespublic Collection withAliases(java.lang.String... aliases)
public java.lang.String getSchemaRef()
public Collection withSchemaRef(java.lang.String schemaRef)
public Collection copy()
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.
public java.lang.String encodeKeyFromColumnNames(java.util.Map<java.lang.String,java.lang.Object> values)
values - a map containing key value pairs for the Collection's primary index using column names not json names.encodeKey(Map, Index, boolean)public java.lang.String encodeKeyFromJsonNames(java.util.Map<java.lang.String,java.lang.Object> values)
values - the key value pairs to encodeencodeKey(Map, Index, boolean)public java.lang.String encodeKeyFromJsonNames(java.util.Map<java.lang.String,java.lang.Object> values,
Index index)
public static java.lang.String encodeKey(java.util.Map<java.lang.String,java.lang.Object> values,
Index index,
boolean useJsonPropertyNames)
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 decodeKey(Index, String, boolean) which is used to
decode inbound Url path and query params to determine which resource is being referenced.
values - column name to Property value mapping for a resourceindex - the index identifying the values that should be encodeduseJsonPropertyNames - use json prop names vs db col namesencodeStr(String),
decodeKey(Index, String, boolean)public static java.lang.String encodeKey(java.util.List pieces)
piecespieces - key parts to be encodedpieces separated by "~" charactersencodeStr(String),
encodeKey(Map, Index, boolean)public java.util.Map<java.lang.String,java.lang.Object> decodeKeyToColumnNames(Index index, java.lang.String inKey)
index - identifies the columnNames by positioninKey - the encoded string to decodedecodeKey(Index, String, boolean),
encodeKey(Map, Index, boolean)public java.util.Map<java.lang.String,java.lang.Object> decodeKeyToJsonNames(java.lang.String inKeys)
inKeys - the resource key to decodedecodeKey(Index, String, boolean),
encodeKey(Map, Index, boolean)public java.util.Map<java.lang.String,java.lang.Object> decodeKey(Index index, java.lang.String key, boolean useJsonPropertyNames)
index - identifies the columnNames to decodekey - a comma separated list of encoded resource keysuseJsonPropertyNames - indicates to preserve json prop names/types and not convert to db column name/typesencodeKey(Map, Index, boolean),
encodeStr(String),
decodeStr(String)Copyright © 2023 Rocket Partners, LLC. All rights reserved.