queries

These queries permit a module to ascertain limited kinds of information about files or other interesting artifacts, where the information is ultimately supplied by a possibly unrelated module, without mandating a direct dependency. The querier is insulated from needing to understand, much less rely on details of, the model used by the query implementation.

Although the queries are heavily used by project-related code, they may be both queried and implemented without any projects at all.

{@link org.netbeans.api.queries.CollocationQuery} checks whether files are logically part of one directory tree and thus whether relative paths between them would have any sense. {@link org.netbeans.api.queries.FileBuiltQuery} can be used to see if a file that can be "built", currently needs to be. {@link org.netbeans.api.queries.SharabilityQuery} checks whether a file is intended to be important data kept in a version-control system.

A query is implemented by creating an instance of its implementation interface and registering it to default lookup. Queriers should normally not need to see these interfaces directly since there is a matching utility class which aggregates and prioritizes the results automatically. The utility class in the API can also insulate clients from changes in the SPI.

It is expected that only a small number of implementations of a given query interface are actually registered at once, so the critical path for answering it should be relatively short. Where a large number of modules are able to supply information for a query following a common structure, and it is possible to quickly determine which one would know the answer, a multiplexing implementation of the query interface may be registered which can reroute requests directly to a proper implementation of some secondary interface (again registered in default lookup). This technique permits the SPI to be very flexible while keeping a typical API method call fast. For an example, note that only one instance of ProjectFactory is necessary to support all Ant-based projects: each project type is defined using an AntBasedProjectType, and the singleton multiplexer delegates appropriately based on the project type ID found in nbproject/project.xml in the project directory. Therefore adding a new Ant-based project type should not increase the time required to recognize a particular Ant-based project on disk.