Interface AnnotationGetterInterface

The AnnotationGetterInterface interface is used to fetch annotations views in groups in the DMU.

Please see Annotations for more explanations about annotations.

The AnnotationGetterInterface interfaces are created through the DataSessionInterface.createAnnotationGetter method.

The list of signals the AnnotationGetterInterface may trigger is available in the AnnotationGetterInterfaceSignal enumeration.

The annotation retrieval request is triggered through the fetchAnnotationGroups method. The result is not available right away, but the event AnnotationGetterInterfaceSignal.AnnotationFetchReady is triggered when the result of the AnnotationGetterInterface is available. The result is available through the getAnnotationGroupsResult function.
As said in Annotations, the annotation groups result consists in opaque annotation view(s) that must be included in an AnnotationRendererInterface to be usable. Each annotation view is itself composed of multiple annotations.

Warning : there may be cases when the getAnnotationGroupsResult is not available such as when the AnnotationGetterInterface is fetching data, i.e. when isRunning returns true, or when the AnnotationGetterInterface has been cancelled, i.e. when isCancelled returns true.

An AnnotationGetterInterface may be interrupted (cancelled) when the AnnotationGetterInterface is running and cancelFetch is called. In such cases, the AnnotationGetterInterfaceSignal.AnnotationFetchCancelled signal is fired, and shortly after, AnnotationGetterInterfaceSignal.AnnotationFetchReady signal is fired, but getAnnotationGroupsResult will return undefined. Just call fetchAnnotationGroups with another (or the same) AnnotationGroupInfoInterface to trigger a new fetch request.

If you call multiple times fetchAnnotationGroups before receiving the AnnotationGetterInterfaceSignal.AnnotationFetchReady, only one AnnotationGetterInterfaceSignal.AnnotationFetchReady will be sent with the content of the last call to fetchAnnotationGroups.

The process is as follows :

• retrieve an AnnotationGroupInfoInterface from an id-card request.
• asynchronously fetch AnnotationResultInterface from the AnnotationGetterInterface.
• extract the AnnotationViewInterfaces and Matrix4 from the AnnotationResultInterface.
• add the AnnotationViewInterface and Matrix4 to the AnnotationRendererInterface.

/** 
 * Sample to illustrate the use of an AnnotationGetterInterface to retrieve multiple annotation views.
 */
import {
    DataSessionInterface, IdCardGetterInterface, IdCardGetterInterfaceSignal, AnnotationGetterInterfaceSignal,
    InfiniteEvent, PartInstanceInfoInterface, AnnotationGroupInfoInterface, AnnotationGetterInterface,
    AnnotationResultInterface, AncestryInstanceMetadataInterface, WorkingSetInterface,
} from 'generated_files/documentation/appinfiniteapi';

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// created previously
let lIdCardGetterInterface : IdCardGetterInterface;
// created previously, the working set to use for the id card query
let lWorkingSet : WorkingSetInterface;
// the part instance id to fetch
let lPartInstanceId : number;

// to retrieve the annotations
const lAnnotationViewGetter : AnnotationGetterInterface = lDataSession.createAnnotationGetter();

// what to do when we have retrieved id card information ?
let onIdCardReady : (_pEvent: InfiniteEvent, _pCallbackData: Object | undefined) => void;

// what to do when annotation data has been downloaded ?
let onAnnotationViewDownloaded : (_pEvent: InfiniteEvent, _pCallbackData: Object | undefined) => void;

// what to do when id card is ready ?
lIdCardGetterInterface.addEventListener(IdCardGetterInterfaceSignal.IdCardReady, onIdCardReady);
// what to do when the download of the annotation view is ready ?
lAnnotationViewGetter.addEventListener(AnnotationGetterInterfaceSignal.AnnotationFetchReady, onAnnotationViewDownloaded);

// onIdCardReady will be called when id-card data is available
onIdCardReady = (_pEvent: InfiniteEvent, _pCallbackData: Object | undefined) : void =>
{
    if (lIdCardGetterInterface.getLastError() !== undefined) {
        // do nothing in case of error
        // perhaps some GUI code ?
    }
    const lPartInstanceInfos : Array<PartInstanceInfoInterface> | undefined = lIdCardGetterInterface.getPartInstanceInfos();
    if (!lPartInstanceInfos || lPartInstanceInfos.length !== 1)
    {
        // no data (isCancelled ?)
        return;
    }
    // get the first the instantiation chain
    const lCurrentChain : PartInstanceInfoInterface = lPartInstanceInfos[0];
    // the annotation views that will be fetched
    const lAnnotationsToFetch : Array<AnnotationGroupInfoInterface> = [];
    // iterate over the metadata infos to retrieve all views at once
    const lAllInstanceMetadata : Array<AncestryInstanceMetadataInterface> = lCurrentChain.getAncestorInstanceInfos();
    // loops
    let i : number;
    let j : number;
    // number of annotation views for this instance
    let lNbAnnotationViews : number;
    // number of ancestors
    const lNbAncestors : number = lAllInstanceMetadata.length;
    let lAnnotationViewsOfPartInstance :Array<AnnotationGroupInfoInterface>;
    let lCurAnnotationView : AnnotationGroupInfoInterface;
    for (i = 0; i < lNbAncestors; i += 1)
    {
        lAnnotationViewsOfPartInstance = lAllInstanceMetadata[i].getAnnotationGroups();
        lNbAnnotationViews = lAnnotationViewsOfPartInstance.length;
        for (j = 0; j < lNbAnnotationViews; j += 1)
        {
            lCurAnnotationView = lAnnotationViewsOfPartInstance[j];
            // some fancy log
            console.log('Will fetch annotation view ' + lCurAnnotationView.getGroupName() + ' of type ' + lCurAnnotationView.getGroupTypeName()
                    + ' with ' + lCurAnnotationView.getAnnotationsCount() + ' annotations');
            // add the annotation view to be fetched
            lAnnotationsToFetch.push(lCurAnnotationView);
        }
    }
    // and download
    lAnnotationViewGetter.fetchAnnotationGroups(lAnnotationsToFetch);
};

// what to do when annotation data has been downloaded ?
onAnnotationViewDownloaded = (_pEvent: InfiniteEvent, _pCallbackData: Object | undefined) : void =>
{
    // annotation are ready
    const lAnnotationViewsContent : Array<AnnotationResultInterface> | undefined = lAnnotationViewGetter.getAnnotationGroupsResult();
    if ((!lAnnotationViewsContent) || (lAnnotationViewsContent.length === 0))
    {
        console.log('error while fetching annotation content');
        return;
    }
    // now annotation content is there, just need to display them
    // use only the first view
    const lCurAnnotationViewResult : AnnotationResultInterface = lAnnotationViewsContent[0];
    console.log('display annotation view ' + lCurAnnotationViewResult.getGroupName() + ' (of type ' + lCurAnnotationViewResult.getGroupTypeName() + ')');
};

lIdCardGetterInterface.retrieveIdCard(lPartInstanceId, lWorkingSet);

Copy

Or with async calls :

/** 
 * Sample to illustrate the asynchronous use of an AnnotationGetterInterface to retrieve multiple annotation views.
 */
import {
    DataSessionInterface, IdCardGetterInterface, AsyncResultReason, AsyncPartInstanceInfoResult,
    PartInstanceInfoInterface, AnnotationGroupInfoInterface, AnnotationGetterInterface, AnnotationResultInterface, AsyncAnnotationResult, AncestryInstanceMetadataInterface, WorkingSetInterface
} from 'generated_files/documentation/appinfiniteapi';

// the DataSessionInterface has been created previously and is connected
let lDataSession : DataSessionInterface;
// created previously
let lIdCardGetterInterface : IdCardGetterInterface;
// created previously, the working set to use for the id card query
let lWorkingSet : WorkingSetInterface;
// the part instance id to fetch
let lPartInstanceId : number;

// to retrieve the annotations
const lAnnotationViewGetter : AnnotationGetterInterface = lDataSession.createAnnotationGetter();

const fetchAnnotation = async () : Promise<void> =>
{
    const lIdCardRes : AsyncPartInstanceInfoResult = await lIdCardGetterInterface.asyncRetrieveIdCard(lPartInstanceId, lWorkingSet);
    if (!lIdCardRes.value || !lIdCardRes.value.length)
    {
        // display some fancy error message
        return;
    }
    console.assert(lIdCardRes.reason === AsyncResultReason.ARR_Success);

    // get the first the instantiation chain
    const lCurrentChain : PartInstanceInfoInterface = lIdCardRes.value[0];
    // the annotation views that will be fetched
    const lAnnotationsToFetch : Array<AnnotationGroupInfoInterface> = [];
    // iterate over the metadata infos to retrieve all views at once
    const lAllInstanceMetadata : Array<AncestryInstanceMetadataInterface> = lCurrentChain.getAncestorInstanceInfos();
    // loops
    let i : number;
    let j : number;
    // number of annotation views for this instance
    let lNbAnnotationViews : number;
    // number of ancestors
    const lNbAncestors : number = lAllInstanceMetadata.length;
    let lAnnotationViewsOfPartInstance :Array<AnnotationGroupInfoInterface>;
    let lCurAnnotationView : AnnotationGroupInfoInterface;
    for (i = 0; i < lNbAncestors; i += 1)
    {
        lAnnotationViewsOfPartInstance = lAllInstanceMetadata[i].getAnnotationGroups();
        lNbAnnotationViews = lAnnotationViewsOfPartInstance.length;
        for (j = 0; j < lNbAnnotationViews; j += 1)
        {
            lCurAnnotationView = lAnnotationViewsOfPartInstance[j];
            // some fancy log
            console.log('Will fetch annotation view ' + lCurAnnotationView.getGroupName() + ' of type ' + lCurAnnotationView.getGroupTypeName()
                    + ' with ' + lCurAnnotationView.getAnnotationsCount() + ' annotations');
            // add the annotation view to be fetched
            lAnnotationsToFetch.push(lCurAnnotationView);
        }
    }
    // and download
    const lAnnotationContentResult : AsyncAnnotationResult = await lAnnotationViewGetter.asyncFetchAnnotationGroups(lAnnotationsToFetch);
    // annotation are ready
    // const lAnnotationViewsContent : Array<AnnotationResultInterface> | undefined = lAnnotationViewGetter.getAnnotationGroupsResult();
    if ((!lAnnotationContentResult.value) || (lAnnotationContentResult.value.length === 0))
    {
        console.log('error while fetching annotation content');
        return;
    }
    // now annotation content is there, just need to display them
    // use only the first view
    const lCurAnnotationViewResult : AnnotationResultInterface = lAnnotationContentResult.value[0];
    console.log('display annotation view ' + lCurAnnotationViewResult.getGroupName() + ' (of type ' + lCurAnnotationViewResult.getGroupTypeName() + ')');
};

fetchAnnotation();

Copy

Please make sure the destination browser supports promises before using async calls.

See

• AnnotationGetterInterfaceSignal
• AnnotationResultInterface
• AnnotationGroupInfoInterface
• AnnotationViewInterface