ShardUtils

ShardUtils is a Spring service that provides methods for managing the OpenKM shard configuration. Shards allow the document repository to be distributed across multiple physical disks or directories. Access it via ContextWrapper.getContext().getBean(ShardUtils.class) or inject it with @Autowired.

Shards are registered in the database. Use getShardIds() to list available shard IDs before calling methods that require a shardId parameter.

Shard configuration

setCurrentShard

Description:

Method	Return values	Description
setCurrentShard(Long shardId)	void	Sets the active shard to the given shard ID. Updates the configuration in the database and reloads it across the cluster if clustering is enabled. Throws `RepositoryException` if the shard ID is not registered.

Example:

package com.openkm;

import com.openkm.util.ContextWrapper;
import com.openkm.util.ShardUtils;

public class Test {

    public static void main(String[] args) {
        try {
            ShardUtils shardUtils = ContextWrapper.getContext().getBean(ShardUtils.class);
            shardUtils.setCurrentShard(1L);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

createShardDirs

Description:

Method	Return values	Description
createShardDirs(Long shardId)	void	Creates the required storage directories for the given shard ID across all tenants. Should be called after registering a new shard in the database. Throws `RuntimeException` if directory creation fails.

Example:

package com.openkm;

import com.openkm.util.ContextWrapper;
import com.openkm.util.ShardUtils;

public class Test {

    public static void main(String[] args) {
        try {
            ShardUtils shardUtils = ContextWrapper.getContext().getBean(ShardUtils.class);
            shardUtils.createShardDirs(2L);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Moving nodes between shards

changeNodeShard

Description:

Method Return values Description

Method	Return values	Description
changeNodeShard(String uuid, Long newShardId)	void	Moves the physical content of the given repository node to the target shard. The behaviour varies by node type: Document: moves all version content files and the text extraction file. Mail: moves the raw mail content, the extraction file, and all attachment child nodes recursively. Folder / Record: applies the move recursively to all child nodes. Throws `RepositoryException` if the target shard is not registered. Throws `IOException` if any file move fails.
uuid: The UUID of the document, folder, mail, or record to move. newShardId: The ID of the destination shard.

changeNodeShard(String uuid, Long newShardId)

void

Moves the physical content of the given repository node to the target shard. The behaviour varies by node type:

Document: moves all version content files and the text extraction file.
Mail: moves the raw mail content, the extraction file, and all attachment child nodes recursively.
Folder / Record: applies the move recursively to all child nodes.

Throws RepositoryException if the target shard is not registered. Throws IOException if any file move fails.

uuid: The UUID of the document, folder, mail, or record to move.

newShardId: The ID of the destination shard.

Example:

package com.openkm;

import com.openkm.util.ContextWrapper;
import com.openkm.util.ShardUtils;

public class Test {

    public static void main(String[] args) {
        try {
            ShardUtils shardUtils = ContextWrapper.getContext().getBean(ShardUtils.class);
            shardUtils.changeNodeShard("e2391b01-ce10-42c7-94a9-b0d6b394048e", 2L);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Querying shards

getShardIds

Description:

Method	Return values	Description
getShardIds()	List<Long>	Returns the list of all registered shard IDs.

getShardSize

Description:

Method	Return values	Description
getShardSize(Long shardId)	Long	Returns the total size in bytes of all content stored in the given shard across all tenants. Throws `DatabaseException` if tenant data cannot be retrieved.

getShardPaths

Description:

Method	Return values	Description
getShardPaths(Long shardId)	List<String>	Returns the list of absolute filesystem paths for the given shard, one per tenant. Throws `DatabaseException` if tenant data cannot be retrieved.

getShards

Description:

Method	Return values	Description
getShards()	List<Shard>	Returns the list of all registered `Shard` entities from the database.

getShardFolders

Description:

Method	Return values	Description
getShardFolders()	List<File>	Returns the list of shard directories found under `Config.REPOSITORY_HOME`. Directories are identified by the configured shard prefix and returned sorted alphabetically.

Example:

package com.openkm;

import com.openkm.db.bean.Shard;
import com.openkm.util.ContextWrapper;
import com.openkm.util.ShardUtils;

import java.io.File;
import java.util.List;

public class Test {

    public static void main(String[] args) {
        try {
            ShardUtils shardUtils = ContextWrapper.getContext().getBean(ShardUtils.class);

            System.out.println("Shard IDs: " + shardUtils.getShardIds());

            for (long id : shardUtils.getShardIds()) {
                System.out.println("Shard " + id + " size: " + shardUtils.getShardSize(id) + " bytes");
                System.out.println("Shard " + id + " paths: " + shardUtils.getShardPaths(id));
            }

            List<Shard> shards = shardUtils.getShards();
            for (Shard shard : shards) {
                System.out.println(shard);
            }

            List<File> folders = shardUtils.getShardFolders();
            for (File f : folders) {
                System.out.println(f.getPath());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Table of contents [ Hide Show ]