@itwin/core-backend
Version:
iTwin.js backend components
502 lines • 21.9 kB
TypeScript
/** @packageDocumentation
* @module ViewDefinitions
*/
import { GuidString, MarkRequired, Optional } from "@itwin/core-bentley";
import { CategorySelectorProps, DisplayStyleLoadProps, DisplayStyleProps, DisplayStyleSettingsProps, ModelSelectorProps, RenderSchedule, RenderTimelineProps, ThumbnailFormatProps, ThumbnailProps, ViewDefinitionProps, ViewStoreRpc } from "@itwin/core-common";
import { CloudSqlite } from "./CloudSqlite";
import { VersionedSqliteDb } from "./SQLiteDb";
import { IModelDb } from "./IModelDb";
import { BlobContainer } from "./BlobContainerService";
/**
* A ViewStore is a database that stores Views and related data. It is used to store and retrieve views for iTwin.js.
* It can either be a local SQLite file, or a CloudSqlite database stored in a cloud container. To use a CloudSqlite
* database, you must first create a container in Blob Storage and then call [[ViewStore.CloudAccess.initializeDb]].
*
* A ViewStore can hold:
* - Views
* - DisplayStyles
* - CategorySelectors
* - ModelSelectors
* - RenderTimelines
* - Searches
* - Tags
* - Thumbnails
* - ViewGroups
*
* Views are added to a ViewStore via ViewDefinitionProps that may hold references to a DisplayStyle, CategorySelector, ModelSelector, or RenderTimeline.
* Before storing a View, you must first add any referenced DisplayStyles, CategorySelectors, ModelSelectors, and RenderTimelines to the
* ViewStore. The "add" methods return a string that uniquely identifies the object in the ViewStore.
* You should set the ViewDefinitionProps's displayStyle, categorySelector, modelSelector, or renderTimeline member to the returned string.
* When you load a ViewDefinition from the ViewStore, the member may be used to load the DisplayStyle, CategorySelector,
* ModelSelector, RenderTimeline, etc.
*
* A IdString is a string that uniquely identifies a row in one of the ViewStore's internal tables. The string holds a base-36 integer
* that starts with "@" (vs. "0x" for ElementIds). For example, if you store a DisplayStyle and it is assigned the ViewStore Id "@y1", then you
* should set the ViewDefinitionProps's displayStyle member to "@y1". When you load the ViewDefinition from the ViewStore, the "@Y1" may be used to
* alo load the DisplayStyle from the ViewStore.
*
* Views are organized into hierarchical ViewGroups (like file and folder hierarchies on a file system). A View is always stored "in" a ViewGroup, and
* views must have a name that is unique within the ViewGroup. ViewGroups may each have a default ViewId.
* The root ViewGroup is named "Root" and has a RowId of 1. The root ViewGroup can not be deleted.
* View names and ViewGroup names may not contain either "/" or "@". ViewGroups are stored in the "viewGroups" table.
*
* Views may be "tagged" with one or more Tags. Tags are named with an arbitrary string that can be used to group Views. A Tag may
* be associated with multiple Views, and a View may have multiple Tags. Tags are stored in the "tags" table.
*
* Views may optionally have a thumbnail, paired via the View's Id. Thumbnails are stored in the "thumbnails" table.
*
* Note: All ElementIds and ModelIds in ModelSelectors, CategorySelectors, DisplayStyles, Timelines, etc. are converted to guid-based identifiers when stored in the ViewStore.
* They are then remapped back to their Ids when loaded from the ViewStore. This allows the ViewStore to be used with more than one iModel,
* provided that the same Guids are used in each iModel. This is done by storing the set of unique Guids in the "guids" table, and then
* creating a reference to the row in the "guids" table via the special Id prefix "^". For example, if a category selector contains the
* Id "0x123", then the guid from element 0x123 is stored in the "guids" table, and the category selector is stored with the rowId of the entry
* in the guid table (e.g. "^1w"). When the category selector is loaded from the ViewStore, the guid is looked up in the "guids" table and
* the iModel is queried for the element with that guid. That element's Id (which may or may not be 0x123) is then returned in the category selector.
*
* @beta
*/
export declare namespace ViewStore {
export const tableName: {
readonly categorySelectors: "categorySelectors";
readonly displayStyles: "displayStyles";
readonly viewGroups: "viewGroups";
readonly guids: "guids";
readonly modelSelectors: "modelSelectors";
readonly taggedViews: "taggedViews";
readonly tags: "tags";
readonly thumbnails: "thumbnails";
readonly timelines: "timelines";
readonly searches: "searches";
readonly views: "views";
};
/** data for a Thumbnail */
type ThumbnailData = Uint8Array;
/** A row in a table. 0 means "not present" */
export type RowId = number;
/** a string representation of a row in a table of a ViewStore. Will be a base-36 integer with a leading "@" (e.g."@4e3") */
type RowString = string;
/** common properties for all tables */
interface TableRow {
name?: string;
json: string;
owner?: string;
}
type DisplayStyleRow = TableRow;
type SelectorRow = TableRow;
type TagRow = TableRow;
type SearchRow = TableRow;
type TimelineRow = TableRow;
/** a row in the "views" table */
interface ViewRow extends MarkRequired<TableRow, "name"> {
className: string;
groupId: RowId;
isPrivate?: boolean;
modelSel?: RowId;
categorySel: RowId;
displayStyle: RowId;
}
/** a row in the "viewGroups" table */
interface ViewGroupRow extends MarkRequired<TableRow, "name"> {
parentId: RowId;
defaultViewId?: RowId;
}
/** a row in the "thumbnails" table */
interface ThumbnailRow {
viewId: RowId;
data: ThumbnailData;
format: ThumbnailFormatProps;
owner?: string;
}
/** convert a RowId to a RowString (base-36 integer with a leading "@") */
export const fromRowId: (rowId: RowId) => RowString;
type RowIdOrString = RowId | RowString;
/** @internal */
export const toRowId: (id: RowIdOrString) => RowId;
export const defaultViewGroupId = 1;
export interface ViewDbCtorArgs {
guidMap?: IModelDb.GuidMapper;
iModel?: IModelDb;
}
export class ViewDb extends VersionedSqliteDb implements ViewStoreRpc.Writer, ReadMethods {
myVersion: string;
private _iModel?;
private _guidMap?;
get guidMap(): IModelDb.GuidMapper;
set guidMap(guidMap: IModelDb.GuidMapper);
get iModel(): IModelDb;
set iModel(iModel: IModelDb);
constructor(arg?: ViewDbCtorArgs);
/** create all the tables for a new ViewDb */
protected createDDL(): void;
/** get the row in the "guids" table for a given guid. If the guid is not present, return 0 */
private getGuidRow;
/** @internal */
getGuid(rowid: RowId): GuidString | undefined;
/** @internal */
iterateGuids(rowIds: RowId[], fn: (guid: GuidString, row: RowId) => void): void;
/** @internal */
addGuid(guid: GuidString): RowId;
/** @internal */
addViewRow(args: ViewRow): RowId;
/** @internal */
addViewGroupRow(args: Optional<ViewGroupRow, "parentId">): RowId;
private addTableRow;
/** add a row to the "modelSelectors" table, return the RowId
* @internal
*/
addModelSelectorRow(args: SelectorRow): RowId;
/** add a row to the "categorySelectors" table, return the RowId
* @internal
*/
addCategorySelectorRow(args: SelectorRow): RowId;
/** add a row to the "displayStyles" table, return the RowId
* @internal
*/
addDisplayStyleRow(args: DisplayStyleRow): RowId;
/** add a row to the "timelines" table, return the RowId
* @internal
*/
addTimelineRow(args: TimelineRow): RowId;
/** add a row to the "tags" table, return the RowId
* @internal
*/
addTag(args: TagRow): RowId;
/** add a row to the "searches" table, return the RowId
* @internal
*/
addSearch(args: SearchRow): Promise<RowId>;
/** add or update a row in the "thumbnails" table, return the RowId
* @internal
*/
addOrReplaceThumbnailRow(args: ThumbnailRow): RowId;
private deleteFromTable;
/** @internal */
deleteViewRow(id: RowIdOrString): void;
deleteViewGroup(args: {
name: ViewStoreRpc.ViewGroupSpec;
}): Promise<void>;
deleteModelSelectorSync(id: RowIdOrString): void;
deleteModelSelector(args: {
id: RowIdOrString;
}): Promise<void>;
deleteCategorySelectorSync(id: RowIdOrString): void;
deleteDisplayStyleSync(id: RowIdOrString): void;
deleteTimelineSync(id: RowIdOrString): void;
deleteTagSync(arg: {
name: ViewStoreRpc.TagName;
}): void;
deleteTag(arg: {
name: ViewStoreRpc.TagName;
}): Promise<void>;
deleteCategorySelector(args: {
id: RowIdOrString;
}): Promise<void>;
deleteDisplayStyle(args: {
id: RowIdOrString;
}): Promise<void>;
deleteTimeline(args: {
id: RowIdOrString;
}): Promise<void>;
deleteSearch(id: RowId): void;
deleteThumbnailSync(id: RowString): void;
deleteThumbnail(arg: {
viewId: RowString;
}): Promise<void>;
/** get the data for a view from the database
* @internal
*/
getViewRow(viewId: RowId): undefined | ViewRow;
/** @internal */
getThumbnailRow(viewId: RowId): undefined | ThumbnailRow;
/** @internal */
getViewGroup(id: RowId): ViewGroupRow | undefined;
private getTableRow;
/** read a ModelSelector given a rowId
* @internal
*/
getModelSelectorRow(id: RowId): SelectorRow | undefined;
/** read a CategorySelector given a rowId
* @internal
*/
getCategorySelectorRow(id: RowId): SelectorRow | undefined;
/** read a DisplayStyle given a rowId
* @internal
*/
getDisplayStyleRow(id: RowId): DisplayStyleRow | undefined;
/** @internal */
getTimelineRow(id: RowId): TimelineRow | undefined;
/** @internal */
getTag(id: RowId): TagRow | undefined;
/** @internal */
getSearch(id: RowId): SearchRow | undefined;
private updateJson;
updateViewShared(arg: {
viewId: RowIdOrString;
isShared: boolean;
owner?: string;
}): Promise<void>;
/** @internal */
updateViewGroupJson(groupId: RowIdOrString, json: string): void;
/** @internal */
updateModelSelectorJson(modelSelectorId: RowIdOrString, json: string): void;
/** @internal */
updateCategorySelectorJson(categorySelectorId: RowIdOrString, json: string): void;
/** @internal */
updateDisplayStyleJson(styleId: RowId, json: string): void;
/** @internal */
updateTimelineJson(timelineId: RowId, json: string): void;
/** @internal */
updateSearchJson(searchId: RowId, json: string): void;
private updateName;
renameView(args: {
viewId: RowIdOrString;
name: string;
}): Promise<void>;
renameViewGroup(args: {
groupId: RowIdOrString;
name: string;
}): Promise<void>;
renameModelSelector(args: {
id: RowIdOrString;
name?: string;
}): Promise<void>;
renameCategorySelector(args: {
id: RowIdOrString;
name?: string;
}): Promise<void>;
renameDisplayStyle(args: {
id: RowIdOrString;
name?: string;
}): Promise<void>;
renameTimeline(args: {
id: RowIdOrString;
name?: string;
}): Promise<void>;
renameSearch(args: {
id: RowIdOrString;
name: string;
}): Promise<void>;
renameTag(args: {
oldName: string;
newName: string;
}): Promise<void>;
/** @internal */
addTagToView(args: {
viewId: RowId;
tagId: RowId;
}): void;
private deleteViewTag;
/** @internal */
findViewsForTag(tagId: RowId): RowId[];
private findByName;
/** @internal */
getViewGroupByName(name: string, parentId: RowId): RowId;
/** @internal */
findModelSelectorByName(name: string): RowId;
/** @internal */
findCategorySelectorByName(name: string): RowId;
/** @internal */
findDisplayStyleByName(name: string): RowId;
/** @internal */
findTagByName(name: string): RowId;
/** @internal */
findTimelineByName(name: string): RowId;
/** @internal */
findSearchByName(name: string): RowId;
private getViewInfoSync;
getViewInfo(args: {
viewId: RowIdOrString;
}): Promise<ViewStoreRpc.ViewInfo | undefined>;
findViewsByOwner(args: {
owner: string;
}): Promise<ViewStoreRpc.ViewInfo[]>;
/** @internal */
findTagIdsForView(viewId: RowId): RowId[];
private toGuidRow;
private toCompressedGuidRows;
private fromGuidRow;
private fromGuidRowString;
private iterateCompressedGuidRows;
private fromCompressedGuidRows;
private toGuidRowMember;
private fromGuidRowMember;
private verifyRowId;
private scriptToGuids;
private scriptFromGuids;
addViewGroup(args: {
name: string;
parentId?: RowString;
owner?: string;
}): Promise<RowString>;
getViewGroups(args: {
parent?: ViewStoreRpc.ViewGroupSpec;
}): Promise<{
id: string;
name: string;
}[]>;
private makeSelectorJson;
private querySelectorValues;
addCategorySelector(args: {
name?: string;
selector: ViewStoreRpc.SelectorProps;
owner?: string;
}): Promise<RowString>;
updateCategorySelector(args: ViewStoreRpc.NameOrId & {
selector: ViewStoreRpc.SelectorProps;
}): Promise<void>;
private getRowId;
/** @internal */
getCategorySelectorSync(args: ViewStoreRpc.NameOrId & ViewStoreRpc.QueryBindings): CategorySelectorProps;
getCategorySelector(args: ViewStoreRpc.NameOrId & ViewStoreRpc.QueryBindings): Promise<CategorySelectorProps>;
addModelSelector(args: {
name?: string;
selector: ViewStoreRpc.SelectorProps;
owner?: string;
}): Promise<RowString>;
updateModelSelector(args: ViewStoreRpc.NameOrId & {
selector: ViewStoreRpc.SelectorProps;
}): Promise<void>;
getModelSelectorSync(args: ViewStoreRpc.NameOrId & ViewStoreRpc.QueryBindings): ModelSelectorProps;
getModelSelector(args: ViewStoreRpc.NameOrId & ViewStoreRpc.QueryBindings): Promise<ModelSelectorProps>;
private makeTimelineJson;
addTimeline(args: {
name?: string;
timeline: RenderSchedule.ScriptProps;
owner?: string;
}): Promise<RowString>;
updateTimeline(args: ViewStoreRpc.NameOrId & {
timeline: RenderSchedule.ScriptProps;
}): Promise<void>;
getTimelineSync(args: ViewStoreRpc.NameOrId): RenderTimelineProps;
getTimeline(args: ViewStoreRpc.NameOrId): Promise<RenderTimelineProps>;
/** make a JSON string for a DisplayStyle */
private makeDisplayStyleJson;
addDisplayStyle(args: {
name?: string;
className: string;
settings: DisplayStyleSettingsProps;
owner?: string;
}): Promise<RowString>;
updateDisplayStyle(args: ViewStoreRpc.NameOrId & {
className: string;
settings: DisplayStyleSettingsProps;
}): Promise<void>;
getDisplayStyleSync(args: ViewStoreRpc.NameOrId & {
opts?: DisplayStyleLoadProps;
}): DisplayStyleProps;
getDisplayStyle(args: ViewStoreRpc.NameOrId & {
opts?: DisplayStyleLoadProps;
}): Promise<DisplayStyleProps>;
private makeViewDefinitionProps;
private addViewDefinition;
updateViewDefinition(args: {
viewId: RowIdOrString;
viewDefinition: ViewDefinitionProps;
}): Promise<void>;
getViewDefinitionSync(args: {
viewId: RowIdOrString;
}): ViewDefinitionProps;
getViewDefinition(args: {
viewId: RowIdOrString;
}): Promise<ViewDefinitionProps>;
addOrReplaceThumbnail(args: {
viewId: RowIdOrString;
readonly thumbnail: ThumbnailProps;
owner?: string;
}): Promise<void>;
getThumbnailSync(args: {
viewId: RowIdOrString;
}): ThumbnailProps | undefined;
getThumbnail(args: {
viewId: RowIdOrString;
}): Promise<ThumbnailProps | undefined>;
/** find a group with the specified name using path syntax (e.g., "group1/design/issues"). If the group does not exist, return 0.
* If groupName starts with "@", then it is considered to be a group id and this function verifies that it exists and throws if it does not.
*/
findViewGroup(groupName: ViewStoreRpc.ViewGroupSpec): RowId;
/**
* find a view by name using path syntax (e.g., "group1/design/issues/issue113"). If the view does not exist, return 0.
* If a groupId is specified, then the view is searched for in that group and the name should not contain a path.
* @internal
*/
findViewIdByName(arg: {
name: string;
groupId?: RowIdOrString;
}): RowId;
getViewByNameSync(arg: {
name: ViewStoreRpc.ViewName;
groupId?: RowIdOrString;
}): ViewStoreRpc.ViewInfo | undefined;
getViewByName(arg: {
name: ViewStoreRpc.ViewName;
groupId?: RowIdOrString;
}): Promise<ViewStoreRpc.ViewInfo | undefined>;
getViewGroupInfo(args: {
groupId?: ViewStoreRpc.IdString;
}): Promise<ViewStoreRpc.ViewGroupInfo | undefined>;
changeDefaultViewId(args: {
defaultView: RowIdOrString;
group?: ViewStoreRpc.ViewGroupSpec;
}): Promise<void>;
/** get the array of tags for the specified view. Returns undefined if the view has no tags. */
getTagsForView(viewId: RowIdOrString): ViewStoreRpc.TagName[] | undefined;
private iterateViewQuery;
queryViewsSync(queryParams: ViewStoreRpc.QueryParams): ViewStoreRpc.ViewInfo[];
queryViews(queryParams: ViewStoreRpc.QueryParams): Promise<ViewStoreRpc.ViewInfo[]>;
addTagsToView(args: {
viewId: RowIdOrString;
tags: string[];
owner?: string;
}): Promise<void>;
removeTagFromView(args: {
viewId: RowIdOrString;
tag: string;
}): Promise<void>;
addView(args: ViewStoreRpc.AddViewArgs): Promise<ViewStoreRpc.IdString>;
deleteView(arg: {
viewId: RowIdOrString;
}): Promise<void>;
}
/** methods of cloud `ViewDb` for read access */
export interface ReadMethods extends ViewStoreRpc.Reader {
getViewByNameSync(arg: {
name: ViewStoreRpc.ViewName;
groupId?: RowId;
}): ViewStoreRpc.ViewInfo | undefined;
getCategorySelectorSync(args: ViewStoreRpc.NameOrId & ViewStoreRpc.QueryBindings): CategorySelectorProps;
getDisplayStyleSync(args: ViewStoreRpc.NameOrId & {
opts?: DisplayStyleLoadProps;
}): DisplayStyleProps;
getModelSelectorSync(args: ViewStoreRpc.NameOrId & ViewStoreRpc.QueryBindings): ModelSelectorProps;
getThumbnailSync(args: {
viewId: RowString;
}): ThumbnailProps | undefined;
getViewDefinitionSync(args: {
viewId: RowString;
}): ViewDefinitionProps;
queryViewsSync(queryParams: ViewStoreRpc.QueryParams): ViewStoreRpc.ViewInfo[];
}
/** arguments to construct a `ViewStore.CloudAccess` */
export type ViewStoreCtorProps = CloudSqlite.ContainerAccessProps & ViewDbCtorArgs;
export interface CreateNewContainerProps {
scope: BlobContainer.Scope;
metadata: Omit<BlobContainer.Metadata, "containerType">;
}
/** Provides access to a cloud-based `ViewDb` */
export class CloudAccess extends CloudSqlite.DbAccess<ViewDb, ReadMethods, ViewStoreRpc.Writer> {
constructor(props: ViewStoreCtorProps);
/**
* Initialize a cloud container for use as a ViewDb. This method is called by [[createNewContainer]].
* It is only necessary to convert an existing container to a ViewStore container.
* @note this deletes any existing content in the container.
* @internal
*/
static initializeDb(props: CloudSqlite.ContainerProps): Promise<void>;
/** Create and initialize a new BlobContainer to hold a ViewStore
* @note the current user must have administrator rights to create containers.
*/
static createNewContainer(args: CreateNewContainerProps): Promise<CloudSqlite.ContainerProps>;
}
export {};
}
//# sourceMappingURL=ViewStore.d.ts.map