Repo library

Contents

Functions related to management of a node repository.

Usage

Add the following to your build.gradle file:

dependencies {
  include xplibs.repo
}

Add the import statement to your code:

import repoLib from '/lib/xp/repo';

You are now ready to use the API.

Events

Usage of this API produces the following events:

Table 1. Distributed events
Event Occurs when

repository.created

a repository is created

repository.updated

a repository is updated

repository.deleted

a repository is deleted

repository.restoreInitialized

a repository restore begins

repository.restored

a repository restore is completed

For more information on events, check out the Event library

Functions

create

Creates a repository.

Parameters

Name Type Description

params

CreateRepositoryParams

JSON with the parameters

Returns

Repository : The created repository.

Examples

import {create} from '/lib/xp/repo';

// Creates a repository with default configuration
const result1 = create({
    id: 'test-repo'
});

log.info('Repository created with id %s', result1.id);
import {create} from '/lib/xp/repo';

// Creates a repository with specific settings
const result2 = create({
    id: 'test-repo2',
    rootPermissions: [
        {
            principal: 'role:admin',
            allow: [
                'READ',
                'CREATE',
                'MODIFY',
                'DELETE',
                'PUBLISH',
                'READ_PERMISSIONS',
                'WRITE_PERMISSIONS'
            ],
            deny: []
        }
    ],
    rootChildOrder: '_ts DESC',
    transient: true
});

log.info('Repository created with id %s', result2.id);
// First repository created.
const expected1 = {
    id: 'test-repo',
    transient: false,
    branches: [
        'master'
    ],
    data: {}
};

createBranch

Creates a branch.

Parameters

Name Type Description

params

CreateBranchParams

JSON with the parameters

Returns

BranchResult : The created branch.

Examples

import {createBranch} from '/lib/xp/repo';

// Creates a branch
try {
    const result = createBranch({
        branchId: 'test-branch',
        repoId: 'my-repo'
    });
    log.info('Branch [%s] created', result.id);
} catch (e) {
    if (e.code == 'branchAlreadyExists') {
        log.error('Branch [features-branch] already exist');
    } else {
        log.error('Unexpected error: %s', e.message);
    }
}

deleteRepo

Deletes a repository.

Renamed from delete to avoid the JavaScript reserved word. The old delete export is still available for backward compatibility.

Parameters

Name Type Description

id

string

Repository ID

Returns

boolean : true if deleted, false otherwise

Examples

import {deleteRepo} from '/lib/xp/repo';

// Deletes a repository
const result = deleteRepo('test-repo');

if (result) {
    log.info('Repository deleted');
} else {
    log.info('Repository was not found');
}

deleteBranch

Deletes a branch.

Parameters

Name Type Description

params

DeleteBranchParams

JSON with the parameters

Returns

BranchResult : The deleted branch.

Examples

import {deleteBranch} from '/lib/xp/repo';

// Deletes a branch
try {
    const result = deleteBranch({
        branchId: 'test-branch',
        repoId: 'my-repo'
    });
    log.info('Branch [%s] deleted', result.id);
} catch (e) {
    if (e.code == 'branchNotFound') {
        log.error('Branch [test-branch] does not exist');
    } else {
        log.error('Unexpected error: %s', e.message);
    }
}

get

Retrieves a repository.

Parameters

Name Type Description

id

string

Repository ID

Returns

Repository | null : The repository, or null if no repository exists with the given id.

Examples

import {get as getRepo} from '/lib/xp/repo';

// Retrieves a repository
const result = getRepo('test-repo');

if (result) {
    log.info('Repository found');
} else {
    log.info('Repository was not found');
}
// Repository retrieved.
const expected = {
    id: 'test-repo',
    transient: false,
    branches: [
        'master'
    ],
    data: {}
};

getBinary

Returns a data stream for a repository attachment.

Parameters

Name Type Description

params

GetRepositoryBinaryParams

JSON with the parameters

Returns

\* : Stream of the attachment data.

Example

import {getBinary} from '/lib/xp/repo';

const binaryStream = getBinary({
    repoId: 'my-repo',
    binaryReference: 'myBinaryReference'
});

list

Retrieves the list of repositories.

Returns

Repository[] : The list of repositories.

Examples

import {list} from '/lib/xp/repo';

// Retrieves the list of repositories
const result = list();
log.info('%s repositories found', result.length);
// Repositories retrieved.
const expected = [{
    id: 'test-repo',
    transient: false,
    branches: [
        'master'
    ],
    data: {}
}, {
    id: 'another-repo',
    transient: false,
    branches: [
        'master'
    ],
    data: {}
}];

modify

Updates a repository.

Parameters

Name Type Description

params

ModifyRepositoryParams

JSON with the parameters

Returns

Repository : The updated repository.

Example

import {modify} from '/lib/xp/repo';

// Update repository data
const result = modify({
    id: 'my-repo',
    editor: (repo) => {
        repo.transient = true;
        repo.data = {
            ...repo.data,
            myString: 'modified',
            myArray: ['modified1', 'modified2', 'modified3']
        };
        return repo;
    }
});

refresh

Refreshes indices in the current repository.

Parameters

Name Type Attributes Description

params

RefreshParams

<optional>

JSON with the parameters

Examples

import {refresh} from '/lib/xp/repo';

// Refresh all for default repository
refresh();
// Refresh storage for default repository
refresh({mode: 'storage'});
// Refresh search for 'system-repo' repository
refresh({
    mode: 'search',
    repo: 'system-repo'
});

Objects

Repository

Repository object returned by create, get, list, and modify.

Fields

Name Type Attributes Description

id

string

Repository ID.

branches

string[]

Branches available in the repository.

data

object

<optional>

Repository data as a key/value map.

transient

boolean

true if the repository is transient (excluded from dumps and snapshots).

CreateRepositoryParams

Object to pass to the create function.

Fields

Name Type Attributes Description

id

string

Repository ID.

rootPermissions

AccessControlEntry[]

<optional>

Array of root permissions. By default, all permissions to role:system.admin and READ permission to role:system.authenticated.

rootChildOrder

string

<optional>

Root child order (for example, _ts DESC).

transient

boolean

<optional>

Mark the repository as transient. Defaults to false.

AccessControlEntry

Permission entry used in CreateRepositoryParams.rootPermissions.

Fields

Name Type Attributes Description

principal

string

Principal key (for example, role:system.admin, user:system:su).

allow

string[]

<optional>

Permissions to grant. Each value is one of READ, CREATE, MODIFY, DELETE, PUBLISH, READ_PERMISSIONS, WRITE_PERMISSIONS.

deny

string[]

<optional>

Permissions to deny. Same set of values as allow.

CreateBranchParams

Object to pass to the createBranch function.

Fields

Name Type Description

branchId

string

Branch ID.

repoId

string

Repository where the branch should be created.

DeleteBranchParams

Object to pass to the deleteBranch function.

Fields

Name Type Description

branchId

string

Branch ID.

repoId

string

Repository where the branch should be deleted.

BranchResult

Object returned by createBranch and deleteBranch.

Fields

Name Type Description

id

string

Branch ID.

ModifyRepositoryParams

Object to pass to the modify function.

Fields

Name Type Description

id

string

Repository ID.

editor

function

Editor callback function. Receives the current Repository and must return the modified repository.

GetRepositoryBinaryParams

Object to pass to the getBinary function.

Fields

Name Type Description

repoId

string

Repository ID.

binaryReference

string

Reference to the binary.

RefreshParams

Object to pass to the refresh function.

Fields

Name Type Attributes Default Description

mode

string

<optional>

all

Index type to be refreshed. One of all, search, or storage.

repo

string

<optional>

Repository ID. Defaults to the repository of the current context.

branch

string

<optional>

Branch. Defaults to the branch of the current context.


Contents

Contents