# Class: ProjectInterface

## ProjectInterface

#### new ProjectInterface(projectId, storageObjectsAccessor, mainLogger, gmeConfig)

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `projectId` | string | Id of project to be opened.
  `storageObjectsAccessor` | object | Exposes loadObject towards the database.
  `mainLogger` | GmeLogger | Logger instance from instantiator.
  `gmeConfig` | GmeConfig |

### Members

#### gmeConfig :GmeConfig

  ##### Type:

  - GmeConfig

#### logger :GmeLogger

  ##### Type:

  - GmeLogger

#### projectId :string

  Unique ID of project, built up by the ownerId and projectName.

  ##### Type:

  - string

  ##### Example

      'guest+TestProject', 'organization+TestProject2'

### Methods

#### createBranch(branchName, newHash [, callback])

  Creates a new branch with head pointing to the provided commit hash.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `branchName` | string |  | Name of branch to create.
  `newHash` | module:Storage~CommitHash |  | New commit hash for branch head.

  `callback`

  function

  <optional>

  If provided no promise will be returned.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `error` | null | Error | The result of the execution.
  `result` | module:Storage~CommitResult | Status about the branch update.

  ##### Returns:

  On success the promise will be resolved with module:Storage~CommitResult result.
  On error the promise will be rejected with Error error.

  Type
    external:Promise

#### createTag(tagName, commitHash [, callback])

  Creates a new tag pointing to the provided commit hash.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `tagName` | string |  | Name of tag to create.
  `commitHash` | module:Storage~CommitHash |  | Commit hash tag will point to.

  `callback`

  function

  <optional>

  If provided no promise will be returned.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `error` | null | Error | The result of the execution.

  ##### Returns:

  On success the promise will be resolved with nothing.
  On error the promise will be rejected with Error error.

  Type
    external:Promise

#### deleteBranch(branchName, oldHash [, callback])

  Deletes the branch.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `branchName` | string |  | Name of branch to create.
  `oldHash` | module:Storage~CommitHash |  | Previous commit hash for branch head.

  `callback`

  function

  <optional>

  If provided no promise will be returned.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `error` | null | Error | The result of the execution.
  `result` | module:Storage~CommitResult | Status about the branch update.

  ##### Returns:

  On success the promise will be resolved with module:Storage~CommitResult result.
  On error the promise will be rejected with Error error.

  Type
    external:Promise

#### deleteTag(tagName [, callback])

  Deletes the given tag.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `tagName` | string |  | Name of tag to delete.

  `callback`

  function

  <optional>

  If provided no promise will be returned.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `error` | null | Error | The result of the execution.

  ##### Returns:

  On success the promise will be resolved with nothing.
  On error the promise will be rejected with Error error.

  Type
    external:Promise

#### getBranches( [callback])

  Retrieves all branches and their current heads within the project.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---

  `callback`

  function

  <optional>

  If provided no promise will be returned.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `error` | null | Error | The result of the execution.
  `branches` | Object.<string, module:Storage~CommitHash> | An object with branch names as keys and their commit-hashes as values.

  ##### Returns:

  On success the promise will be resolved with Object.<string, module:Storage~CommitHash> branches.
  On error the promise will be rejected with Error error.

  Type
    external:Promise

#### getBranchHash(branchName [, callback])

  Retrieves the commit hash for the head of the branch.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `branchName` | string |  | Name of branch.

  `callback`

  function

  <optional>

  If provided no promise will be returned.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `error` | null | Error | The result of the execution.
  `commitHash` | module:Storage~CommitHash | The commit hash.

  ##### Returns:

  On success the promise will be resolved with module:Storage~CommitHash commitHash.
  On error the promise will be rejected with Error error.

  Type
    external:Promise

#### getCommitObject(branchNameOrCommitHash [, callback])

  Retrieves the commit-object at the provided branch or commit-hash.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `branchNameOrCommitHash` | string |  | Name of branch or a commit-hash.

  `callback`

  function

  <optional>

  If provided no promise will be returned.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `error` | null | Error | The result of the execution.
  `commit` | module:Storage~CommitObject | The commit-object.

  ##### Returns:

  On success the promise will be resolved with module:Storage~CommitObject commitObject.
  On error the promise will be rejected with Error error.

  Type
    external:Promise

#### getCommits(before, number [, callback])

  Retrieves and array of the latest (sorted by timestamp) commits for the project. If timestamp is given it will get number of commits strictly before before. If commit hash is specified that commit will be included too.
  N.B. due to slight time differences on different machines, ancestors may be returned before their descendants. Unless looking for 'headless' commits 'getHistory' is the preferred method.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `before` | number | module:Storage~CommitHash |  | Timestamp or commitHash to load history from.
  `number` | number |  | Number of commits to load.

  `callback`

  function

  <optional>

  If provided no promise will be returned.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `error` | null | Error | The result of the execution.
  `commits` | Array.<module:Storage~CommitObject> | The commits that match the input, ordered by their time of insertion.

  ##### Returns:

  On success the promise will be resolved with Array.<module:Storage~CommitObject> commits.
  On error the promise will be rejected with Error error.

  Type
    external:Promise

#### getCommonAncestorCommit(commitA, commitB [, callback])

  Retrieves the common ancestor of two commits. If no ancestor exists it will result in an error.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `commitA` | module:Storage~CommitHash |  | Commit hash.
  `commitB` | module:Storage~CommitHash |  | Commit hash.

  `callback`

  function

  <optional>

  If provided no promise will be returned.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `error` | null | Error | The result of the execution (will be non-null if e.g. the commits do not exist or have no common ancestor).
  `commitHash` | module:Storage~CommitHash | The commit hash of the common ancestor.

  ##### Returns:

  On success the promise will be resolved with module:Storage~CommitHash commitHash.
  On error the promise will be rejected with Error error.

  Type
    external:Promise

#### getHistory(start, number [, callback])

  Retrieves an array of commits starting from a branch(es) and/or commitHash(es).
  The result is ordered by the rules (applied in order)
  1. Descendants are always returned before their ancestors.
  2. By their timestamp.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `start` | string | module:Storage~CommitHash | Array.<string> | Array.<module:Storage~CommitHash> |  | Branch name, commit hash or array of these.
  `number` | number |  | Number of commits to load.

  `callback`

  function

  <optional>

  If provided no promise will be returned.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `error` | null | Error | The result of the execution.
  `commits` | Array.<module:Storage~CommitObject> | The commits that match the input ordered as explained.

  ##### Returns:

  On success the promise will be resolved with Array.<module:Storage~CommitObject> commits.
  On error the promise will be rejected with Error error.

  Type
    external:Promise

#### getProjectInfo( [callback])

  Retrieves the metadata of the project.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---

  `callback`

  function

  <optional>

  If provided no promise will be returned.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `error` | null | Error | The result of the execution.
  `projectInfo` | object | An object with info about the project.

  ##### Returns:

  On success the promise will be resolved with {object} projectInfo.
  On error the promise will be rejected with Error error.

  Type
    external:Promise

  ##### Example

      {
       _id: 'guest+example',
       owner: 'guest',
       name: 'example',
       info: {
           createdAt: '2016-12-02T17:52:25.029Z',
           viewedAt: '2017-01-30T22:45:15.269Z',
           modifiedAt: '2017-01-20T00:15:34.593Z',
           creator: 'guest',
           viewer: 'guest',
           modifier': 'guest'
       },
       hooks: {
           ConstraintCheckerHook': {
               url: 'http://127.0.0.1:8080/ConstraintCheckerHook',
               description': 'Checks if there are any meta violations in the project',
               events: ['COMMIT'],
               active: true,
               createdAt: '2017-01-19T23:22:46.834Z',
               updatedAt: '2017-01-19T23:22:46.834Z'
           }
       },
       rights: {
           read: true,
           write: true,
           delete: true
       },
       branches: {
           b1: '#998067142c7ff8067cd0c04a0ec4ef80d865606c',
           master: '#36df6f8c17b2ccf4e35a2a75b1e0adb928f82a61'
       }
      }

#### getRootHash(branchNameOrCommitHash [, callback])

  Retrieves the root hash at the provided branch or commit-hash.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `branchNameOrCommitHash` | string |  | Name of branch or a commit-hash.

  `callback`

  function

  <optional>

  If provided no promise will be returned.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `error` | null | Error | The result of the execution.
  `rootHash` | module:Core~ObjectHash | The root hash.

  ##### Returns:

  On success the promise will be resolved with module:Core~ObjectHash rootHash.
  On error the promise will be rejected with Error error.

  Type
    external:Promise

#### getTags( [callback])

  Retrieves all tags and their commits hashes within the project.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---

  `callback`

  function

  <optional>

  If provided no promise will be returned.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `error` | null | Error | The result of the execution.
  `tags` | Object.<string, module:Storage~CommitHash> | An object with tag names as keys and their commit-hashes as values.

  ##### Returns:

  On success the promise will be resolved with Object.<string, module:Storage~CommitHash> tags.
  On error the promise will be rejected with Error error.

  Type
    external:Promise

#### getUserId()

  Return the identity of the current user of this project.

  ##### Returns:

  the userId

  Type
    string

#### makeCommit(branchName, parents, rootHash, coreObjects, msg [, callback])

  Makes a commit to data base. Based on the root hash and commit message a new module:Storage.CommitObject (with returned hash) is generated and insert together with the core objects to the database on the server.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `branchName` | string |  |  | Name of branch to update (none if null).
  `parents` | Array.<module:Storage~CommitHash> |  |  | Parent commit hashes.
  `rootHash` | module:Core~ObjectHash |  |  | Hash of root object.
  `coreObjects` | module:Core~DataObject |  |  | Core objects associated with the commit.
  `msg` | string |  | 'n/a' | Commit message.

  `callback`

  function

  <optional>

  If provided no promise will be returned.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `error` | null | Error | The result of the execution.
  `result` | module:Storage~CommitResult | Status about the commit and branch update.

  ##### Returns:

  On success the promise will be resolved with module:Storage~CommitResult result.
  On error the promise will be rejected with {Error} error.

  Type
    external:Promise

  ##### Examples

      var persisted = core.persist(rootNode);

      project.makeCommit('master', ['#thePreviousCommitHash'], persisted.rootHash, persisted.objects, 'new commit')
        .then(function (result) {
          // result = {
          //   status: 'SYNCED',
          //   hash: '#thisCommitHash'
          // }
        })
        .catch(function (error) {
          // error.message = 'Not authorized to read project: guest+project'
        });

      project.makeCommit('master', ['#notPreviousCommitHash'], persisted.rootHash, persisted.objects, 'new commit')
        .then(function (result) {
          // result = {
          //   status: 'FORKED',
          //   hash: '#thisCommitHash'
          // }
        })...

      project.makeCommit(null, ['#anExistingCommitHash'], persisted.rootHash, persisted.objects, 'new commit')
        .then(function (result) {
          // result = {
          //   hash: '#thisCommitHash'
          // }
        })...

      project.makeCommit('master', ['#aPreviousCommitHash'], previousRootHash, {}, 'adding a commit to master')
        .then(function (result) {
          // result = {
          //   status: 'SYNCED',
          //   hash: '#thisCommitHash'
          // }
        })...

#### setBranchHash(branchName, newHash, oldHash [, callback])

  Updates the head of the branch.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `branchName` | string |  | Name of branch to update.
  `newHash` | module:Storage~CommitHash |  | New commit hash for branch head.
  `oldHash` | module:Storage~CommitHash |  | Current state of the branch head inside the database.

  `callback`

  function

  <optional>

  If provided no promise will be returned.

  ###### Properties

  Name | Type | Description
  --- | --- | ---
  `error` | null | Error | The result of the execution.
  `result` | module:Storage~CommitResult | Status about the branch update.

  ##### Returns:

  On success the promise will be resolved with module:Storage~CommitResult result.
  On error the promise will be rejected with Error error.

  Type
    external:Promise

### Type Definitions

#### loadObjectCallback(err, object)

  Callback for loadObject.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `err` | Error | If error occurred.
  `object` | module:Storage~CommitObject | module:Core~ObjectData | Object loaded from database, commit-object or model data-blob.

#### Search results