Custom I/O for Stream Cache

Stream Cache servers do their I/O over a pair of abstract classes. This allows a user to write their own classes that inherit from these abstract base classes to customize I/O. This can be useful if you want to, for example, do your SC I/O over websockets or another protocol, or lay your files out in a way that would make them normally unreadable by the default SC filesystem methods.

In order to specify an AbstractFilesystem you only need to provide a pointer to it in your SC::Server::StreamCacheServer::Config.

When opening SCZ files for viewing, they will need to be extracted. To do this, they are unzipped and their contents written to the workspace, which is specified as part of SC::Server::StreamCacheServer::Config.

The abstract classes

There are two classes that need to be implemented: AbstractFilesystem and AbstractFile. Both can be found in sc_io.h.

AbstractFilesystem

This provides libsc with the means to navigate the filesystem and query files. The following methods will need to be implemented:

Method

Description

std::unique_ptr<AbstractFile> NewFile()

Creates a new object inherited from AbstractFile.

std::unique_ptr<AbstractFile> NewFile(path const& path)

Creates a new AbstractFile object with a path.

path Cleaned(path const& path) const

Cleans a path. For example, removes .. and ..

bool Exists(path const& path) const

Returns true if a file or directory exists at path.

bool IsDirectory(path const& path) const

Returns true if a directory exists at path.

bool IsRegularFile(path const& path) const

Returns true if a regular file (not a directory or symlink) exists at path.

bool IsSymlink(path const& path) const

Returns true if a symlink exists at path.

bool IsEmpty(path const& path) const

Returns true if the file or directory at path is empty.

void GetChildren(path const& path, std::vector<IO::path>& out_children) const

Fills out_children with the children of the directory at path.

uintmax_t RemoveAll(path const& path)

Removes everything in the directory at path. Returns the number of items removed.

bool Remove(path const& path)

Removes the file at path. Returns true if successful.

bool Rename(path const& old_path, path const& new_path)

Renames the file at old_path to new_path. Returns true if successful.

bool CreateDir(path const& path)

Creates a directory at path. Returns true if successful.

bool CreateDirs(path const& path)

Creates a directory at path. Creating any other directories needed ahead of it. Returns true if successful.

AbstractFile

This provides libsc with the means to interact with files, including reading and writing data. The following methods will need to be implemented:

Method

Description

State DoAcquire(bool read_only, bool create_if_missing, bool truncate)

Acquires the resource. At the very least this must update the _state property to indicate the mode the file was opened in, or if it has failed to open. Returns the state that was set.

void DoRelease()

Releases the resource (closes the file).

int64_t DoSeek(int64_t offset, Position position)

Moves the read/write offset to somewhere within the file. Can be offset from the beginning, current position or end depending on the position argument. Returns the offset from the beginning of the file.

bool DoTruncate()

Truncates data after the current offset. Returns true if successful.

int64_t DoGetSize() const

Gets the size of the file.

size_t DoRead(void* data, size_t n_bytes)

Reads n_bytes from the file starting at the offset into data. data should already be allocated to hold n_bytes. Retuns the number of bytes read.

size_t DoWrite(void const* data, size_t n_bytes)

Writes n_bytes from data into the file starting at the offset. Returns the number of bytes written.

bool DoFlush()

Flush the cache, if any. Returns true if successful.

Node SC server REST I/O

The node server included with the HOOPS Communicator package is capable of doing I/O over REST for use cases where you might want to read SC data directly over the network. To make use of this, you’d write a server that exposes a REST API that the SC server would communicate with to query and retrieve SC data.

Usage with the Node server

To use REST with the node server included with the package, a few things will need to be set up.

In your config, you’ll need to set the restFileserver parameter to the address of your REST file server.

The paths that will be requested from your REST server will be dependent on the modelDirs parameter in your config. For example, if your SC server is on Windows, your modelDirs parameter is set to ["C:\\models"] and when you request myModel, you can expect to see queries about C:\\models\\myModel.

The API

All endpoints should send JSON responses except read which sends an octet-stream.

Endpoint

Parameters

Description

Returns

/read/:path

offset, size

Reads size number of bytes from the file at path, starting at offset

An octet-stream with the requested bytes

/exists/:path

None

Checks if the file or directory at path exists

{ exists: boolean }

/size/:path

None

Returns the size of a file

{ size: u64 }

/isDir/:path

None

Checks if path is a directory

{ isDir: boolean }

/isRegularFile/:path

None

Checks if path is a regular file (not a directory or a symlink)

{ isRegularFile: boolean }

/isSymlink/:path

None

Checks if path is a symlink

{ isSymlinkFile: boolean }

/isEmpty/:path

None

Checks if the file or directory at path is empty (no contents or zero bytes)

{ isEmpty: boolean }

/getChildren/:path

None

Gets the children of the directory at path

{ children: string[] }