define([
'viewmodel/js/api/Archetype'
], function(
    Archetype) {

    'use strict';

    /**
     * {@link viewmodel/js/api/Archetype Archetype} representing a single record
     * for a businness object.
     *
     * As it mostly covers use-cases related to work with a form it also provides
     * operations related to the bound Business Object, for example
     * {@link viewmodel/js/api/DetailArchetype#save save one record} or
     * {@link viewmodel/js/api/DetailArchetype#getRecord get viewed record}.
     *
     * @AbcsAPI stable
     * @version 16.3.5
     * @exports viewmodel/js/api/DetailArchetype
     * @constructor
     * @private
     * @augments viewmodel/js/api/Archetype
     * @param {entity/js/api/Entity} entity
     * @param {Object} descriptor JSON archetype descriptor
     */
    var DetailArchetype = function (entity, descriptor) {
        AbcsLib.checkThis(this);
        Archetype.call(this, entity, descriptor);
    };
    AbcsLib.extend(DetailArchetype, Archetype);

    /**
     * Returns current record represented by this archetype instance. The returned
     * object can be used to alter current record data.
     *
     * You will need to get the record for the most of {@link module:api/js/Pages Navigation API}
     * methods when passing data between pages, see an example below.
     *
     * @AbcsAPI stable
     * @version 16.3.5
     * @returns {viewmodel/js/api/Record} object holding current data
     * @example <caption>Get the current record and pass it to the edit customer page</caption>
     * var customerToEdit = ContextualData.createRecordToEditContext({
     *      // what business object are these data of:
     *      entityId: 'customer',
     *      // pass the currently viewed customer record
     *      data: customerDetailArchetype.getRecord()
     * });
     * // navigate to the customer edit page
     * Abcs.Pages().navigateToPage('customerEditPage', customerToEdit);
     */
    DetailArchetype.prototype.getRecord = function () {};

    /**
     * Save the given record, that is create or update a record according to its
     * state.
     *
     * The state is determined by the way the archetype's owning page was opened
     * and what {@link viewmodel/js/api/context/ContextualData ContextualData}
     * passed to the page through the {@link module:api/js/Pages Navigation API}.
     * If e.g. {@link viewmodel/js/api/context/ContextualData.createRecordToEditContext ContextualData.createRecordToEditContext}
     * is used to create the data passed to the page, the archetype will be in
     * the <i>edit mode</i>. On the other hand {@link viewmodel/js/api/context/ContextualData.createStartWithBlankRecordContext ContextualData.createStartWithBlankRecordContext}
     * determines the <i>create mode</i>.
     *
     * The method merely saves the passed record and stays on the same page. If
     * you wish to pass the saved record forward to another page (such as move to
     * a detail page after saving the record) you will need to use the {@link module:api/js/Pages Navigation API}
     * manually to do so.
     *
     * @AbcsAPI stable
     * @version 16.3.5
     * @param {viewmodel/js/api/Record} record to save
     * @returns {Promise} promise resolved to saved {@link viewmodel/js/api/Record record}
     * instance when the save successfully finishes and rejected in case of an error.
     * @example <caption>Modify the current record and save the changes</caption>
     * // get the current live archetype's instance of a Record
     * var customerRecord = customerEditArchetype.getRecord();
     *
     * // get number of orders the customer has made so far
     * var numberOfOrders = customerRecord.getValue('numberOfOrders');
     *
     * // check if number of orders is more than five and promote the customer
     * // to a Premium state
     * if (numberOfOrders > 5) {
     *     customerRecord.setValue('state', 'Premium');
     *
     *     // save the modifications
     *     customerEditArchetype.save(customerRecord).then(function () {
     *         console.log('Successfully saved.');
     *     });
     * }
     */
    DetailArchetype.prototype.save = function(/*record*/) {};

    /**
     * Register hooks into the DetailArchetype notifying about load and save
     * operations.
     *
     * @param {Object} handlerRegistration { loadHandler: function(Record), saveHandler: function(Record), beforeSaveHandler: function(Record) }
     */
    DetailArchetype.prototype.registerHandlers = function (/*handlerRegistration*/) {};

    /**
     * Unregister hooks from the DetailArchetype
     * operations.
     *
     * @see {@link module:viewmodel/js/api/DetailArchetype.registerHandlers}
     * @param {Object} handlerRegistration { loadHandler: function(), saveHandler: function() }
     */
    DetailArchetype.prototype.unregisterHandlers = function (/*handlerRegistration*/) {};

    /**
     * Returns an object that contains a set of fields and observables you can
     * bind to in your components and use to communicate with other components on
     * a page bound to the same fields.
     *
     * @AbcsAPI stable
     * @version 16.3.5
     * @returns {viewmodel/js/api/DetailArchetype~DetailObservables} observables exposed by the archetype
     * @function
     */
    DetailArchetype.prototype.getObservables = Archetype.prototype.getObservables;

    /**
     * Contains set of fields and observables you can bind to in your components
     * and use to communicate with other components on a page bound to the same
     * fields.
     *
     * Besides the published observables you may use archetype's methods to
     * interact with it.
     *
     * @AbcsAPI stable
     * @typedef viewmodel/js/api/DetailArchetype~DetailObservables
     * @property {Object<String, ko.observable>} record map of {@link http://knockoutjs.com/documentation/observables.html ko observables}
     * wrapping values of all fields of the Business Object the archetype is bound to.
     * Unlike {@link DetailArchetype.getRecord DetailArchetype.getRecord}
     * this allows you to bind your HTML view directly to the field value and
     * read or modify it immediately via {@link http://knockoutjs.com/documentation/introduction.html ko binding}.
     * See the example below.
     * @property {Object<String, ko.observable>} item <em>Deprecated</em>, use DetailObservables.record instead.
     * Map of {@link http://knockoutjs.com/documentation/observables.html ko observables}
     *
     * @version 16.3.5
     * @example <caption>Bind to the customer's last name directly from an HTML
     * element with ko binding</caption>
     * <label for="customerLastName">Customer last name</label>
     * <input id="customerLastName" data-bind="value: $root.Observables.customerFormArchetype.record.lastName"></input>
     *
     * @example <caption>Use the observables in custom code and listen for changes
     * in a REFERENCE type field value.</caption>
     * // subscribe to the ko observable to catch its value changes
     * var record = pageModel.Observables.customerFormArchetype.record;
     * var subscription = record.refToCustomer.subscribe(function (newCustomerId) {
     *   console.log('New Customer ID value is: ' + newCustomerId);
     *   // do something here related to your model
     * });
     * ...
     * // do not forget to dispose the listener when no longer needed.
     * subscription.dispose();
     *
     */

    return DetailArchetype;

});