/* eslint-disable no-unused-vars */
define([
'core/js/api/Implementations'
], function(
Implementations
) {
'use strict';
/**
* An API factory object to create instances of various data model related objects.
*
* <p>
* Please be aware that using <code>DataModelFactory</code> is supposed to be used only in {@link bop/js/spi/BOP BOP} implementation (specifically to be used inside
* custom {@link bop/js/spi/entity/EntityProvider EntityProvider} implementation). But it for example doesn't make sense to create an {@link entity/js/api/Entity Entity}
* instance inside your custom component code because such {@link entity/js/api/Entity Entity} will never be properly registered into Application Builder data model.
* </p>
*
* @AbcsExtension stable
* @version 17.1.1
* @exports bop/js/api/entity/DataModelFactory
*
* @private
* @constructor
*
* @see {@link entity/js/api/Entity Entity} representing an entity object
* @see {@link entity/js/api/Property Property} representing a property of an entity
* @see {@link entity/js/api/Relation Relation} representing a relation between two entities
* @see {@link bop/js/spi/entity/EntityProvider EntityProvider} which is the place where <code>DataModelFactory</code> should be mainly used
*/
var DataModelFactory = function() {
AbcsLib.throwStaticClassError();
};
/**
* Creates a new instance of {@link entity/js/api/Entity Entity} object.
*
* @AbcsExtension stable
* @version 17.1.1
*
* @param {Object} params - An Object literal with following properties.
* @param {String} params.id - Unique ID of the created {@link entity/js/api/Entity Entity}.
* @param {String} params.singularName - Singular name for the created {@link entity/js/api/Entity Entity}.
* @param {String} [params.pluralName] - Plural name for the created {@link entity/js/api/Entity Entity}.
* @param {String} [params.description] - Human-readable description of what's the meaning of the created {@link entity/js/api/Entity Entity}.
* @param {entity/js/api/Property[]} params.properties - Array of {@link entity/js/api/Property properties} assigned to the created {@link entity/js/api/Entity Entity}.
* @returns {entity/js/api/Entity}
*
* @example
* <caption>
* Creates simple {@link entity/js/api/Entity Entity} with three {@link entity/js/api/Property properties}.
* </caption>
*
* var firstName = DataModelFactory.createProperty({
* id: 'firstname',
* name: 'Firstname',
* type: PropertyType.TEXT
* });
* var lastName = DataModelFactory.createProperty({
* id: 'lastname',
* name: 'Lastname',
* type: PropertyType.TEXT
* });
* var age = DataModelFactory.createProperty({
* id: 'age',
* name: 'Age',
* type: PropertyType.NUMBER
* });
* var employee = DataModelFactory.createEntity({
* id: 'my.custom.bop.Employee',
* singularName: 'Employee',
* pluralName: 'Employees',
* description: 'Business object representation of Employee object',
* properties: [firstName, lastName, age]
* });
*
* @see {@link entity/js/api/Entity Entity} representing an entity object
* @see {@link entity/js/api/Property Property} representing a property of an entity
*/
DataModelFactory.createEntity = function(params) {
return getImplementation().createEntity(params);
};
/**
* Creates a new instance of {@link entity/js/api/Property Property} object.
*
* @AbcsExtension stable
* @version 17.1.1
*
* @param {Object} params - An Object literal with following properties
* @param {String} params.id - ID of the created {@link entity/js/api/Property Property}
* @param {String} params.name - Name of the created {@link entity/js/api/Property Property}.
* @param {entity/js/api/PropertyType} params.type - {@link entity/js/api/PropertyType Type} of the created {@link entity/js/api/Property Property}.
* @param {String} [params.initialValue] - Initial value which will be set for the created {@link entity/js/api/Property Property} if no other value will be provided.
* @param {entity/js/api/PropertyClassification} [params.classification={@link entity/js/api/PropertyClassification.BASIC PropertyClassification.BASIC}] - {@link entity/js/api/PropertyClassification Classification} of the created {@link entity/js/api/Property Property}.
* @returns {entity/js/api/Property}
*
* @example
* <caption>
* Creates an instance of a {@link entity/js/api/Property Property} initialized with mandatory parameters only.
* </caption>
* var firstname = DataModelFactory.createProperty({
* id: 'firstname',
* name: 'Firstname',
* type: PropertyType.TEXT
* });
*
* @example
* <caption>
* Creates an instance of a {@link entity/js/api/Property Property} initialized with all possible input parameters.
* </caption>
* var hiddenField = DataModelFactory.createProperty({
* id: 'hiddenField',
* name: 'Hidden Field',
* type: PropertyType.NUMBER,
* classification: PropertyClassification.IGNORE,
* initialValue: 'Value not defined yet.'
* });
*
* @see {@link entity/js/api/Property Property} representing a property of an entity
* @see {@link entity/js/api/PropertyType PropertyType} for list of all available {@link entity/js/api/PropertyType PropertyType}s
* @see {@link entity/js/api/PropertyClassification PropertyClassification} for list of all available {@link entity/js/api/PropertyClassification PropertyClassification}s
*/
DataModelFactory.createProperty = function(params) {
return getImplementation().createProperty(params);
};
/**
* Creates a new relation between two {@link entity/js/api/Entity Entities}.
*
* <p>
* Creating relation in fact creates a new {@link entity/js/api/Property Property} in the source {@link entity/js/api/Entity Entity}. Such {@link entity/js/api/Property Property} has always
* type set to {@link entity/js/api/PropertyType.REFERENCE Property.REFERENCE} and it's value is either ID referencing target {@link entity/js/api/Entity Entity} record or can be empty in case
* of no target {@link entity/js/api/Entity Entity} record assigned.
* </p>
*
* <p>
* Please note that although the method returns an instance of {@link entity/js/api/Relation Relation} object, usual API client don't need to process that instance anyhow. Currently it's part of the
* documentation just for it's completeness and it will be extended with more functionality in the future versions of Application Builder APIs.
* </p>
*
* @AbcsExtension stable
* @version 17.1.1
*
* @param {Object} params - An object literal with following properties
* @param {entity/js/api/Entity} params.sourceEntity - {@link entity/js/api/Entity Entity} being considered as source. Source {@link entity/js/api/Entity Entity} always contains the reference to the target.
* @param {entity/js/api/Entity} params.targetEntity - {@link entity/js/api/Entity Entity} being considered as target.
* @param {entity/js/api/RelationCardinality} params.cardinality - {@link entity/js/api/RelationCardinality Cardinality} of the created relation.
* @param {String} params.propertyId - ID of the created reference {@link entity/js/api/Property Property}.
* @param {String} [params.propertyName=Singular name of the target {@link entity/js/api/Entity Entity}] - Name of the created reference {@link entity/js/api/Property Property}.
* @param {entity/js/api/Property} [params.displayNameProperty=Primary key {@link entity/js/api/Property Property} from the target {@link entity/js/api/Entity Entity}] - Default {@link entity/js/api/Property Property} display name of the referenced column. The display name will be used as the target’s property value. See also the example below.
* @param {Boolean} [params.childRelationship=false] - <code>true</code> if this relation is a Parent/Child relationship type or <code>false</code> if it's relation between two standalone objects.
* @returns {entity/js/api/Relation}
*
* @example
* <caption>
* Creates a new relation where Employee {@link entity/js/api/Entity Entity} holds a reference to Department {@link entity/js/api/Entity Entity}.
* </caption>
* // Let's assume two entities already exists: Employee (ID, Firstname, Lastname) and Department (ID, Name)
* DataModelFactory.createRelation({
* sourceEntity: employee,
* targetEntity: department,
* cardinality: RelationCardinality.MANY_TO_ONE,
* propertyId: 'ref2Department'
* });
*
* @example
* <caption>
* Specifies also default display name property to show Department name automatically on all relevant places.
* For example Employee table configured to show Firstname, Lastname and Department columns will always show department name value instead of department ID.
* </caption>
* // Let's assume two entities already exists: Employee (ID, Firstname, Lastname) and Department (ID, Name)
* DataModelFactory.createRelation({
* sourceEntity: employee,
* targetEntity: department,
* cardinality: RelationCardinality.MANY_TO_ONE,
* propertyId: 'ref2Department',
* displayNameProperty: department.getProperty('name')
* });
*
* @example
* <caption>
* Creates a new relation with all mandatory and optional parameters specified.
* </caption>
* // Let's assume two entities already exists: Employee (ID, Firstname, Lastname) and Department (ID, Name)
* DataModelFactory.createRelation({
* sourceEntity: employee,
* targetEntity: department,
* cardinality: RelationCardinality.MANY_TO_ONE,
* propertyId: 'ref2Department',
* propertyName: 'Reference to Department',
* displayNameProperty: department.getProperty('name'),
* childRelationship: true
* });
*
* @see {@link entity/js/api/Entity Entity} representing an entity object
* @see {@link entity/js/api/Property Property} representing a property of an entity
* @see {@link entity/js/api/Relation Relation} representing a relation between two entities
* @see {@link entity/js/api/RelationCardinality RelationCardinality} listing all possible cardinalitites
*/
DataModelFactory.createRelation = function(params) {
return getImplementation().createRelation(params);
};
/**
* Gets one of the implementation of {@link bop/js/api/entity/DataModelFactory DataModelFactory}.
*
* @returns {bop/js/DataModelFactoryBase | bop.dt/js/DataModelFactoryDt}
*/
function getImplementation() {
return Implementations.getImplementation('DataModelFactory');
}
return DataModelFactory;
});
