Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Elevate BackendHubAccess to public, remove deprecated 3.x APIs in core-backend #7587

Draft
wants to merge 4 commits into
base: master
Choose a base branch
from
Draft

Elevate BackendHubAccess to public, remove deprecated 3.x APIs in core-backend #7587

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
877456d
remove transformer related apis
hl662 Jan 22, 2025
8994b1f
Elevate BackendHubAccess, IModelHost.hubAccess to public
hl662 Jan 22, 2025
3c1e378
remove deprecated APIs in core-backend
hl662 Jan 22, 2025
a28ebae
rush change, rush lint, rush extract api
hl662 Jan 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 23 additions & 64 deletions common/api/core-backend.api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -346,16 +346,17 @@ export interface AzureBlobStorageCredentials {
baseUrl?: string;
}

// @internal
// @public
export interface BackendHubAccess {
// @internal
acquireLocks: (arg: BriefcaseDbArg, locks: LockMap) => Promise<void>;
acquireNewBriefcaseId: (arg: AcquireNewBriefcaseIdArg) => Promise<BriefcaseId>;
createNewIModel: (arg: CreateNewIModelProps) => Promise<GuidString>;
deleteIModel: (arg: IModelIdArg & ITwinIdArg) => Promise<void>;
downloadChangeset: (arg: DownloadChangesetArg) => Promise<ChangesetFileProps>;
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@GytisCepk I ran extract-api and it threw warnings for 2 methods, saying it uses args (DownloadChangesetArg and DownloadChangesetRangeArg) that are marked as @beta for this API I just converted to @public... git blame showed you most recently worked on this, do you think those args are okay to move to public or should we move BackendHubAccess to @beta instead

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I expect DownloadChangesetRangeArg to break due to #7357. So we might mark it @public to just deprecate it soon after.

That being said, if there is no other concerns about making BackendHubAccess public, I would go ahead and mark both DownloadChangesetArg and DownloadChangesetRangeArg public.

downloadChangesets: (arg: DownloadChangesetRangeArg) => Promise<ChangesetFileProps[]>;
// @deprecated
downloadV1Checkpoint: (arg: CheckpointArg) => Promise<ChangesetIndexAndId>;
// @internal @deprecated
downloadV1Checkpoint: (arg: DownloadRequest) => Promise<ChangesetIndexAndId>;
getChangesetFromNamedVersion: (arg: IModelIdArg & {
versionName: string;
}) => Promise<ChangesetProps>;
Expand All @@ -367,11 +368,14 @@ export interface BackendHubAccess {
pushChangeset: (arg: IModelIdArg & {
changesetProps: ChangesetFileProps;
}) => Promise<ChangesetIndex>;
// @internal
queryAllLocks: (arg: BriefcaseDbArg) => Promise<LockProps[]>;
queryChangeset: (arg: ChangesetArg) => Promise<ChangesetProps>;
queryChangesets: (arg: ChangesetRangeArg) => Promise<ChangesetProps[]>;
queryIModelByName: (arg: IModelNameArg) => Promise<GuidString | undefined>;
// @internal
queryV2Checkpoint: (arg: CheckpointProps) => Promise<V2CheckpointAccessProps | undefined>;
// @internal
releaseAllLocks: (arg: BriefcaseDbArg) => Promise<void>;
releaseBriefcase: (arg: BriefcaseIdArg) => Promise<void>;
}
Expand Down Expand Up @@ -824,9 +828,6 @@ export class ChannelRootAspect extends ElementUniqueAspect {
static insert(iModel: IModelDb, ownerId: Id64String, channelName: string): void;
}

// @internal @deprecated (undocumented)
export type CheckpointArg = DownloadRequest;

// @internal (undocumented)
export class CheckpointManager {
static downloadCheckpoint(request: DownloadRequest): Promise<void>;
Expand Down Expand Up @@ -1802,14 +1803,8 @@ export class ECDb implements IDisposable {
// @internal
prepareSqliteStatement(sql: string, logErrors?: boolean): SqliteStatement;
prepareStatement(ecsql: string, logErrors?: boolean): ECSqlStatement;
// @deprecated
query(ecsql: string, params?: QueryBinder, options?: QueryOptions): AsyncIterableIterator<any>;
// @deprecated
queryRowCount(ecsql: string, params?: QueryBinder): Promise<number>;
// @internal
resetSqliteCache(size: number): void;
// @deprecated
restartQuery(token: string, ecsql: string, params?: QueryBinder, options?: QueryOptions): AsyncIterableIterator<any>;
saveChanges(changesetName?: string): void;
withPreparedSqliteStatement<T>(sql: string, callback: (stmt: SqliteStatement) => T, logErrors?: boolean): T;
withPreparedStatement<T>(ecsql: string, callback: (stmt: ECSqlStatement) => T, logErrors?: boolean): T;
Expand Down Expand Up @@ -2034,17 +2029,13 @@ class Element_2 extends Entity {
// (undocumented)
static get className(): string;
code: Code;
// @beta @deprecated
protected collectPredecessorIds(predecessorIds: EntityReferenceSet): void;
// (undocumented)
protected collectReferenceIds(referenceIds: EntityReferenceSet): void;
delete(): void;
federationGuid?: GuidString;
getClassMetaData(): EntityMetaData | undefined;
getDisplayLabel(): string;
getJsonProperty(nameSpace: string): any;
// @beta @deprecated
getPredecessorIds(): Id64Set;
getToolTipMessage(): string[];
getUserProperties(namespace: string): any;
insert(): string;
Expand Down Expand Up @@ -2336,13 +2327,9 @@ export class Entity {
get classFullName(): string;
static get className(): string;
get className(): string;
// @internal @deprecated
protected collectReferenceConcreteIds: (_referenceIds: EntityReferenceSet) => void;
// @beta
protected collectReferenceIds(_referenceIds: EntityReferenceSet): void;
forEachProperty(func: PropertyCallback, includeCustom?: boolean): void;
// @internal @deprecated
getReferenceConcreteIds: () => EntityReferenceSet;
// @beta
getReferenceIds(): EntityReferenceSet;
id: Id64String;
Expand Down Expand Up @@ -2565,11 +2552,6 @@ export class ExternalSourceAspect extends ElementMultiAspect {
elementId: Id64String;
aspectId: Id64String;
}>;
// @deprecated (undocumented)
static findBySource(iModelDb: IModelDb, scope: Id64String, kind: string, identifier: string): {
elementId?: Id64String;
aspectId?: Id64String;
};
identifier: string;
jsonProperties?: string;
kind: string;
Expand Down Expand Up @@ -3081,7 +3063,7 @@ export class HubMock {
// (undocumented)
static downloadChangesets(arg: DownloadChangesetRangeArg): Promise<ChangesetFileProps[]>;
// (undocumented)
static downloadV1Checkpoint(arg: CheckpointArg): Promise<ChangesetIndexAndId>;
static downloadV1Checkpoint(arg: DownloadRequest): Promise<ChangesetIndexAndId>;
// (undocumented)
static findLocalHub(iModelId: GuidString): LocalHub;
static getChangesetFromNamedVersion(arg: IModelIdArg & {
Expand Down Expand Up @@ -3121,12 +3103,6 @@ export class HubMock {
static startup(mockName: LocalDirName, outputDir: string): void;
}

// @beta @deprecated (undocumented)
export const IModelCloneContext: typeof IModelElementCloneContext;

// @beta @deprecated (undocumented)
export type IModelCloneContext = IModelElementCloneContext;

// @public
export abstract class IModelDb extends IModel {
// @internal (undocumented)
Expand Down Expand Up @@ -3245,16 +3221,12 @@ export abstract class IModelDb extends IModel {
// @internal
prepareSqliteStatement(sql: string, logErrors?: boolean): SqliteStatement;
prepareStatement(sql: string, logErrors?: boolean): ECSqlStatement;
// @deprecated
query(ecsql: string, params?: QueryBinder, options?: QueryOptions): AsyncIterableIterator<any>;
// @internal
queryAllUsedSpatialSubCategories(): Promise<SubCategoryResultRow[]>;
queryEntityIds(params: EntityQueryParams): Id64Set;
queryFilePropertyBlob(prop: FilePropertyProps): Uint8Array | undefined;
queryFilePropertyString(prop: FilePropertyProps): string | undefined;
queryNextAvailableFileProperty(prop: FilePropertyProps): number;
// @deprecated
queryRowCount(ecsql: string, params?: QueryBinder): Promise<number>;
querySchemaVersion(schemaName: string): string | undefined;
// @internal
querySubCategories(categoryIds: Iterable<Id64String>): Promise<SubCategoryResultRow[]>;
Expand All @@ -3269,8 +3241,6 @@ export abstract class IModelDb extends IModel {
requestSnap(sessionId: string, props: SnapRequestProps): Promise<SnapResponseProps>;
// @internal (undocumented)
restartDefaultTxn(): void;
// @deprecated
restartQuery(token: string, ecsql: string, params?: QueryBinder, options?: QueryOptions): AsyncIterableIterator<any>;
// @internal (undocumented)
restartTxnSession(): void;
// @internal @deprecated (undocumented)
Expand Down Expand Up @@ -3395,8 +3365,6 @@ export namespace IModelDb {
}): Promise<ViewStore.CloudAccess>;
static readonly defaultQueryParams: ViewQueryParams;
getThumbnail(viewDefinitionId: Id64String): ThumbnailProps | undefined;
// @deprecated (undocumented)
getViewStateData(viewDefinitionId: ViewIdString, options?: ViewStateLoadProps): ViewStateProps;
getViewStateProps(viewDefinitionId: ViewIdString, options?: ViewStateLoadProps): Promise<ViewStateProps>;
// (undocumented)
get hasViewStore(): boolean;
Expand Down Expand Up @@ -3573,7 +3541,6 @@ export interface IModelHostOptions {
// @internal
crashReportingConfig?: CrashReportingConfig;
enableOpenTelemetry?: boolean;
// @internal
hubAccess?: BackendHubAccess;
// @internal
logTileLoadTimeThreshold?: number;
Expand Down Expand Up @@ -4746,30 +4713,22 @@ export class RenderMaterialElement extends DefinitionElement {
toJSON(): RenderMaterialProps;
}

// @public (undocumented)
export namespace RenderMaterialElement {
// @deprecated
export class Params {
constructor(paletteName: string);
color?: RgbFactorProps;
description?: string;
diffuse?: number;
finish?: number;
normalMap?: NormalMapProps & {
scale?: number;
};
paletteName: string;
patternMap?: TextureMapProps;
reflect?: number;
reflectColor?: number[];
specular?: number;
specularColor?: RgbFactorProps;
transmit?: number;
}
}

// @public
export interface RenderMaterialElementParams extends RenderMaterialElement.Params {
export interface RenderMaterialElementParams {
color?: RgbFactorProps;
description?: string;
diffuse?: number;
finish?: number;
normalMap?: NormalMapProps & {
scale?: number;
};
paletteName: string;
patternMap?: TextureMapProps;
reflect?: number;
reflectColor?: number[];
specular?: number;
specularColor?: RgbFactorProps;
transmit?: number;
}

// @public
Expand Down
9 changes: 1 addition & 8 deletions common/api/summary/core-backend.exports.csv
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ public;class;AuxCoordSystem3d
public;class;AuxCoordSystemSpatial
beta;interface;AvailableCoordinateReferenceSystemProps
beta;interface;AzureBlobStorageCredentials
internal;interface;BackendHubAccess
public;interface;BackendHubAccess
public;enum;BackendLoggerCategory
public;type;BindParameter
public;class;BisCoreSchema
Expand Down Expand Up @@ -39,8 +39,6 @@ beta;interface;ChannelControl
beta;namespace;ChannelControl
beta;type;ChannelKey
public;class;ChannelRootAspect
internal;type;CheckpointArg
deprecated;type;CheckpointArg
internal;class;CheckpointManager
public;interface;CheckpointProps
public;class;ClassRegistry
Expand Down Expand Up @@ -233,10 +231,6 @@ public;class;GroupInformationModel
public;class;GroupInformationPartition
public;class;GroupModel
internal;class;HubMock
beta;const;IModelCloneContext
deprecated;const;IModelCloneContext
beta;type;IModelCloneContext
deprecated;type;IModelCloneContext
public;class;IModelDb
public;namespace;IModelDb
internal;enum;TileContentState
Expand Down Expand Up @@ -341,7 +335,6 @@ beta;class;RecipeDefinitionElement
public;class;Relationship
public;class;Relationships
public;class;RenderMaterialElement
public;namespace;RenderMaterialElement
public;interface;RenderMaterialElementParams
public;class;RenderMaterialOwnsRenderMaterials
public;class;RenderTimeline
Expand Down
10 changes: 10 additions & 0 deletions common/changes/@itwin/core-backend/nam-deprecate-core-backend_2025-01-22-16-02.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"changes": [
{
"packageName": "@itwin/core-backend",
"comment": "Elevate BackendHubAccess to public, remove deprecated 3.x APIs in core-backend",
"type": "none"
}
],
"packageName": "@itwin/core-backend"
}
10 changes: 2 additions & 8 deletions core/backend/src/BackendHubAccess.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,12 +167,6 @@ export interface DownloadChangesetRangeArg extends ChangesetRangeArg, DownloadPr
targetDir: LocalDirName;
}

/**
* @deprecated in 3.x. Use [[DownloadRequest]].
* @internal
*/
export type CheckpointArg = DownloadRequest;

/**
* Arguments to create a new iModel in iModelHub
* @public
Expand All @@ -188,7 +182,7 @@ export interface CreateNewIModelProps extends IModelNameArg {
* Generally direct access to these methods should not be required, since higher-level apis are provided.
* @note This interface is implemented in another repository. Any changes made to this interface must be validated against
* the implementation found here: https://github.com/iTwin/imodels-clients/blob/main/itwin-platform-access/imodels-access-backend/src/BackendIModelsAccess.ts
* @internal
* @public
*/
export interface BackendHubAccess {
/** Download all the changesets in the specified range. */
Expand Down Expand Up @@ -223,7 +217,7 @@ export interface BackendHubAccess {
* @deprecated in 3.x. V1 checkpoints are deprecated. Download V2 checkpoint using [[V2CheckpointManager.downloadCheckpoint]].
* @internal
*/
downloadV1Checkpoint: (arg: CheckpointArg) => Promise<ChangesetIndexAndId>; // eslint-disable-line @typescript-eslint/no-deprecated
downloadV1Checkpoint: (arg: DownloadRequest) => Promise<ChangesetIndexAndId>;

/**
* Get the access props for a V2 checkpoint. Returns undefined if no V2 checkpoint exists.
Expand Down
67 changes: 1 addition & 66 deletions core/backend/src/ECDb.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
*/
import { assert, DbResult, IDisposable, Logger, OpenMode } from "@itwin/core-bentley";
import { IModelJsNative } from "@bentley/imodeljs-native";
import { DbQueryRequest, ECSchemaProps, ECSqlReader, IModelError, QueryBinder, QueryOptions, QueryOptionsBuilder } from "@itwin/core-common";
import { DbQueryRequest, ECSchemaProps, ECSqlReader, IModelError, QueryBinder, QueryOptions } from "@itwin/core-common";
import { BackendLoggerCategory } from "./BackendLoggerCategory";
import { ConcurrentQuery } from "./ConcurrentQuery";
import { ECSqlStatement } from "./ECSqlStatement";
Expand Down Expand Up @@ -314,69 +314,4 @@ export class ECDb implements IDisposable {
return new ECSqlReader(executor, ecsql, params, config);
}

/** Execute a query and stream its results
* The result of the query is async iterator over the rows. The iterator will get next page automatically once rows in current page has been read.
* [ECSQL row]($docs/learning/ECSQLRowFormat).
*
* See also:
* - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
* - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
*
* @param ecsql The ECSQL statement to execute
* @param params The values to bind to the parameters (if the ECSQL has any).
* @param options Allow to specify certain flags which control how query is executed.
* @returns Returns the query result as an *AsyncIterableIterator<any>* which lazy load result as needed. The row format is determined by *rowFormat* parameter.
* See [ECSQL row format]($docs/learning/ECSQLRowFormat) for details about the format of the returned rows.
* @throws [IModelError]($common) If there was any error while submitting, preparing or stepping into query
* @deprecated in 3.7. Use [[createQueryReader]] instead; it accepts the same parameters.
*/
public async * query(ecsql: string, params?: QueryBinder, options?: QueryOptions): AsyncIterableIterator<any> {
const builder = new QueryOptionsBuilder(options);
const reader = this.createQueryReader(ecsql, params, builder.getOptions());
while (await reader.step())
yield reader.formatCurrentRow();
}
/** Compute number of rows that would be returned by the ECSQL.
*
* See also:
* - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
* - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
*
* @param ecsql The ECSQL statement to execute
* @param params The values to bind to the parameters (if the ECSQL has any).
* See "[iTwin.js Types used in ECSQL Parameter Bindings]($docs/learning/ECSQLParameterTypes)" for details.
* @returns Return row count.
* @throws [IModelError]($common) If the statement is invalid
* @deprecated in 3.7. Count the number of results using `count(*)` where the original query is a subquery instead. E.g., `SELECT count(*) FROM (<query-whose-rows-to-count>)`.
*/
public async queryRowCount(ecsql: string, params?: QueryBinder): Promise<number> {
for await (const row of this.createQueryReader(`SELECT count(*) FROM (${ecsql})`, params)) {
return row[0] as number;
}
throw new IModelError(DbResult.BE_SQLITE_ERROR, "Failed to get row count");
}

/** Cancel any previous query with same token and run execute the current specified query.
* The result of the query is async iterator over the rows. The iterator will get next page automatically once rows in current page has been read.
* [ECSQL row]($docs/learning/ECSQLRowFormat).
*
* See also:
* - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
* - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
*
* @param ecsql The ECSQL statement to execute
* @param token None empty restart token. The previous query with same token would be cancelled. This would cause
* exception which user code must handle.
* @param params The values to bind to the parameters (if the ECSQL has any).
* @param options Allow to specify certain flags which control how query is executed.
* @returns Returns the query result as an *AsyncIterableIterator<any>* which lazy load result as needed. The row format is determined by *rowFormat* parameter.
* See [ECSQL row format]($docs/learning/ECSQLRowFormat) for details about the format of the returned rows.
* @throws [IModelError]($common) If there was any error while submitting, preparing or stepping into query
* @deprecated in 3.7. Use [[createQueryReader]] instead. Pass in the restart token as part of the `config` argument; e.g., `{ restartToken: myToken }` or `new QueryOptionsBuilder().setRestartToken(myToken).getOptions()`.
*/
public async * restartQuery(token: string, ecsql: string, params?: QueryBinder, options?: QueryOptions): AsyncIterableIterator<any> {
for await (const row of this.createQueryReader(ecsql, params, new QueryOptionsBuilder(options).setRestartToken(token).getOptions())) {
yield row;
}
}
}
Loading
Loading