Package org.jetbrains.mps.openapi.module

Interface SearchScope

public interface SearchScope

Should be used only as find usages search scope. BEWARE, API here is inconsistent and may be counter-intuitive. In fact, this interface addresses two distinct aspects. First one is to supply set of models/modules where Finder shall look for occurrences. Another is to help finders deal with SModuleReference/SModelReference they may encounter while doing their job. These are resolve(SModelReference), resolve(SModuleReference) and resolve(SNodeReference). General rule is that for reference to any module/model that are part of search scope, respective resolve shall answer with a model object. These methods, however, are not limited to modules/models of the search scope, and may answer models/modules/nodes from a broader scope. Their primary use is to support queries with references instead of full-fledged objects. When a Finder receives a query to find SNodeReference, it might need a mechanism to obtain SNode from the reference, and it uses respective methods of this interface.

Indeed, resolve() functionality shall be separate and either extracted into dedicated Resolver interface available through jetbrains.mps.ide.findusages.model.SearchQuery or replaced with SRepository available separately. Perhaps, if the only legitimate use of resolve() is query input, jetbrains.mps.ide.findusages.model.holders.IHolder needs re-work to pass objects, rather than references (resolve them externally to Finder).

There's now SearchObjectResolver responsible to translate IHolder's values into model objects, and resolve() methods of this interface serve as fall-back solution only.

Besides, presence of both getModels() and getModules() method is confusing as well, as there's no contract whether they are synchronized/aligned (i.e. if getModules() yields modules for any model from getModels() and vice versa, if a presence of module means its models would be among getModels(). E.g. if a Finder looks in models, does it need to combine getModels() + getModules().selectMany(m->m.getModels()) or not? What if a Finder is capable to look into both SModule and SModel?

Having said that, it's apparent the interface (and Find Usages subsystem) deserves thorough refactoring/redesign. Alas, there's not enough outer pressure yet to push the change, and we move on, with this comment in a desperate hope future generations forgive us.

Method Summary

Modifier and Type	Method	Description
Iterable<SModel>	getModels()
Iterable<SModule>	getModules()
SModel	resolve(SModelReference reference)	Finder use this method to go from model reference to SModel object, Find Usages client may use this method to limit what's visible/accessible to a Finder.
default SNode	resolve(SNodeReference reference)	Find out if a node is visible in the scope.
SModule	resolve(SModuleReference reference)	Finder use this method to go from module reference to SModule object, Find Usages client may use this method to limit what's visible/accessible to a Finder.

Method Detail

getModules

@NotNull
Iterable<SModule> getModules()

Returns:

all modules jetbrains.mps.ide.findusages.findalgorithm.finders.Finder shall look into for occurrences

getModels

@NotNull
Iterable<SModel> getModels()

Returns:

all models jetbrains.mps.ide.findusages.findalgorithm.finders.Finder shall look into for occurrences

resolve

@Nullable
SModel resolve(@NotNull
               SModelReference reference)

Finder use this method to go from model reference to SModel object, Find Usages client may use this method to limit what's visible/accessible to a Finder. Generally, finder use this method to resolve references to search values shall always resolve references to models from getModels()

Parameters:

reference - model to look up in the scope

Returns:

model instance, or null if model with specified reference is not visible in the scope

resolve

@Nullable
SModule resolve(@NotNull
                SModuleReference reference)

Finder use this method to go from module reference to SModule object, Find Usages client may use this method to limit what's visible/accessible to a Finder. shall always resolve references to modules from getModules()

Parameters:

reference - module to look up in the scope

Returns:

module instance, or null if there's no such module in the scope

resolve

@Nullable
default SNode resolve(@NotNull
                      SNodeReference reference)

Find out if a node is visible in the scope. Caller is responsible to ensure proper model access

Parameters:

reference - node to look up in the scope

Returns:

node instance of null if scope doesn't know it.