 | InDesign SDK 20.5 |
| InDesign SDK 20.5 |
#include <IRIDX.h>
Public Types | |
| enum | { kDefaultIID = IID_IRIDX } |
| enum | QueryType { kDynamicQuery = 0, kLockedQuery = 1 } |
| enum | CoherencyType { kCoherentAtOutermostQueryCreation = 0, kCoherentAtThisQueryCreation = 1 } |
| typedef std::vector< RIDXTarget > | Targets |
| typedef std::vector< RIDXSource > | Sources |
| typedef std::vector < RIDXReference > | References |
Public Member Functions | |
| virtual void | Initialize ()=0 |
| virtual void | ProcessScheduledIndexing ()=0 |
| virtual IRIDXQuery * | CreateQuery (QueryType queryType, CoherencyType coherencyType) const =0 |
| virtual bool | HasOutstandingQuery () const =0 |
| virtual bool | HasOutstandingLockedQuery () const =0 |
| virtual void | WontProcessScheduledIndexing ()=0 |
| virtual bool | UpdateInProgress () const =0 |
 Public Member Functions inherited from IPMUnknown | |
| virtual IPMUnknown * | QueryInterface (PMIID interfaceID) const =0 |
| virtual void | AddRef () const =0 |
| virtual void | Release () const =0 |
The public interface of the reference index.
<pre>
One index to hold them all
One query to find them
One interface to observe them all
And during persistence bind them
</pre>
Particular database types (e.g. documents) are reference indexed, which means
that the object model automatically tracks which UIDs in the database are referred
to by which other UIDs, and you may query for this information instead of iterating
the database somehow to obtain it. A particular database has a reference index if the
IRIDXAccess interface is available off of the root object of the database (e.g. kDocBoss in
the case of documents). You can check a reference index as follows:
<pre>
InterfacePtr<IRIDX> ridx (RIDXAccess::QueryRIDX());
if (ridx) ridx->UseSomeFunction();
</pre>
If you are only interested in querying the reference index, you may safely stop reading
further here and refer to CreateQuery().
While the presence of IRIDXAccess on the database's root object means that type of
database is reference indexed, that fact alone does not _create_ the reference
index itself in the database. This is something that must be done when
new databases are created, or when existing ones are opened that could have
been created before reference indexing was performed on that type of database.
Also, each time a database is opened, you must request that the reference index
process any pending indexing that was deferred due to missing plug-ins. For example,
imagine the OpenDoc() function for some database type that is reference indexed.
It should have logic that looks something like the following:
<pre>
InterfacePtr<IRIDX> ridx (RIDXAccess::QueryRIDX());
ridx->Intialize ();
Call Converison Manager HERE if necessary ridx->ProcessScheduledIndexing ();
In the NewDoc() function, handling would be largely identical except there would never be need to call the conversion manager.
| enum IRIDX::CoherencyType |
Specifies whether a query requires the reference index to be brought up to date always, or only if it is outmost query
| enum IRIDX::QueryType |
Specifies whether changes made to the model are reflected in the reference index state during the lifetime of a query
| pure virtual |
Starts a query operation on the reference index.
To query the reference index, call this function. It creates a query and returns a query object that can subsequently be used to interrogate the reference index. The lifetime of the query is the lifetime of the IRIDXQuery object - when the reference count of that object drops to zero the query ends. It is acceptable to aquire one or more additional query objects before the first one is destroyed.
There are two considerations when creating a query: The first is where to require coherency (the reference index is said to be coherent when its state reflects exactly that state of the object model). The second is whether object model changes made during a query may be reflected in the reference index state during the query lifetime (a dynamic query) or not (a locked query).
When you begin to interrogate the reference index by creating the first outstanding query object, the reference index state must be made coherent by forcing all dirty objects in the database to persist themselves. This is a non-trivial amount of work. After this persistence completes, not all dirty objects may be considered "clean," and thus the next time you require coherency (even if the model has not changed in between) you will still force some objects to persist themselves - again a non-trivial overhead.
When you create a query object, you must specify whether to force the reference index coherent only if this query is the outermost query, or whether to always force it consistent. Prefer usage patterns that only require coherency at the outmost query context. If you need to interrogate the reference index multiple times within a small scope, prefer usage patterns that re-use a query object or keep an active query versus creating a single query, releasing it, create a single query, releasing it, etc..., which adds substantial overhead by repeatedly forcing coherency.
If you create a dynamic query, then during the query lifetime if you make changes to the model you may see none, some, or all of your changes reflected in the state of the reference index. This may require some defensive programming to properly handle, but this type of query is the most efficient and permits an arbitrary number of model changes during the query lifetime. Prefer usage patterns that can utilize dynamic queries.
If you create a locked query, then any changes you make to the model during the query lifetime are not reflected in the reference index during the query lifetime. The state of the reference index is frozen when the first locked query is created, and remains frozen until the last outstanding locked query is released. However, because an outstanding locked query freezes its state, changing the model will cause change records for the reference index to be queued up in memory and not applied until later no locked queries are actuve. An arbitrarily large number of model changes during a locked query could exhaust memory and cause failure. Future implementations may be capable of spilling change records to disk to avoid this problem.
There is no such thing as a "coherent query" - i.e. where the reference index constantly reflects the exact state of the model.
It is best to to keep a query object around over a small scope of repeated use, but certainly not much longer than necessary. It is not permissible to keep a query active beyond the end of the outermost executing command or sequence, for example, and this restriction will be enforced via protective shutdown by the architecture.
| queryType | specifies a locked or dynamic query |
| coherencyType | specifies the coherency constraints at the start of the query |
| pure virtual |
Determines if there are any outstanding locked queries.
| pure virtual |
Determines if there are any outstanding queries (either dynamic or locked).
| pure virtual |
Initalize the reference index for the database. This will create the reference index storage if necessary. This function must be called EVERY TIME a reference indexed database is created or opened (but BEFORE conversion).
| pure virtual |
Processes any pending indexing that has been scheduled. This function must be called EVERY TIME a reference indexed database is created or opened (but AFTER conversion).
| pure virtual |
Find out if update is in progress.
| pure virtual |
Tells the reference index that we are closing a reference indexed database very early (it's not going to be saved), that we won't actually call ProcessScheduledIndexing(), and to suppress the assert it would normally give in that case telling you you forgot the call to ProcessScheduledIndexing().
1.8.3.1