ExternalScriptInformationProvider

package saker.build.scripting.model.info

public interface ExternalScriptInformationProvider

Interface for providing information for script models to improve user experience.

External script information providers are used by scripting models to provide better information about various script elements. Information providers can be queried to provide suggestions for script models, or retrieve information for a given context. Most commonly they are used to enhance information tooltips and better content assist proposals based on the contextual informations in the script.

Important: Implementations of external script information providers should provide their results as quickly as possible. It is in order to not hinder user experience, and to be able to provide information to the user quickly. If they need to fetch information over the network, they should start a background thread, asynchronously retrieve the related data and cache it for future callse. When the next time an information is queried, they can return the cached data quickly, without contacting the servers again.

It is acceptable to return incomplete data for the first calls of the methods, and return complete data after the background fetch is done.

External script information providers often have a parent object which might have shorter lifetime. (E.g. a BuildRepository might be closed before the information provider is released)
When the parent object is closed, the information provider should gracefully handle that and not throw any exceptions, but return empty results. Closing the parent object should stop any background fetching.

The scheduling of background communication is implementation dependent to the information provider.

Methods

public default LiteralInformation	getLiteralInformation(String literal, TypeInformation typecontext) Gets information about a literal with optional type context hint.
public default Collection<? extends LiteralInformation>	getLiterals(String literalkeyword, TypeInformation typecontext) Gets information about literals based on a hint keyword and type context hint.
public default Map<TaskName, ? extends TaskInformation>	getTaskInformation(TaskName taskname) Gets the task informations based on a task name hint.
public default Map<TaskName, ? extends TaskParameterInformation>	getTaskParameterInformation(TaskName taskname, String parametername) Gets information about a task parameter.
public default Map<TaskName, ? extends TaskInformation>	getTasks(String tasknamekeyword) Gets information about tasks based on a hint keyword.

public default LiteralInformation getLiteralInformation(String literal, TypeInformation typecontext)

Gets information about a literal with optional type context hint.

Implementations should return information about the literal to display to the user. The literal should be exactly matched, and not as a keyword hint.

The type context information may be used to determine how to interpred the argument literal. It may be null. It should be an instance that this information provider previously returned, however implementations are recommended to handle the case when the caller fails to adhere to this requirement.

This method is usually used when the user explicitly requests information about a given literal token in the script.

literalThe literal to query the informations for.

typecontextThe type information context hint or null if not available.

The information about the literal or null if not available.

public default Collection<? extends LiteralInformation> getLiterals(String literalkeyword, TypeInformation typecontext)

Gets information about literals based on a hint keyword and type context hint.

Implementations should discover possible literals that are related with the given keyword. The key word can be interpreted in any way the implementation decides to handle. As a general rule of thumb the key word should be used to discover literals that start with it, however implementations can deviate from this rule.

The type context information can serve as a hint to what kind of literals should be returned. It should be an instance that this information provider previously returned, however implementations are recommended to handle the case when the caller fails to adhere to this requirement.

The literal and type context hints may be null, but at least one of them will be non-null.

The literal keyword hint should be interpreted the same way as in getTaskInformation(TaskName). Implementations should only return literals that are related to the specified keyword.

The resulting collection should be ordered based on relevance to the hint parameters. We recommend using LinkedHashSet to keep the insertion order for the returned literals.

This method is usually useful when creating completion proposals for a script model.

literalkeywordThe literal hint or null if not available.

typecontextThe type information context hint or null if not available.

The literal informations.

public default Map<TaskName, ? extends TaskInformation> getTaskInformation(TaskName taskname)

Gets the task informations based on a task name hint.

This method queries the information provider for task informations based on a hint task name. The provider should interpret the task name as an exact match, and the task qualifiers as a hint for the returned results.

The returned map should be ordered based on the relevance of the related task. Implementations are recommended to use a map which keeps the insertion order, such as LinkedHashMap.

The value informations in the returned map are allowed to be lazily populated. The values in the map can be null to signal that they are not available or are still pending due to background retrieval.

tasknameThe task name hint. Never null.

The informations for related tasks.

public default Map<TaskName, ? extends TaskParameterInformation> getTaskParameterInformation(TaskName taskname, String parametername)

Gets information about a task parameter.

This method queries the information provider for task parameter informations based on a hint task name and an exact parameter name. The parameter name passed as argument should match the informations returned in the result. The provider should interpret the task name as an exact match, and the task qualifiers as a hint for the returned results.

The returned map should be ordered based on the relevance of the related task. Implementations are recommended to use a map which keeps the insertion order, such as LinkedHashMap.

The value informations in the returned map are allowed to be lazily populated. The values in the map cannot be null.

Task parameter names should be matched using the rules specified in TaskParameterInformation. Also see ScriptInfoUtils.isCompatibleParameterName(String, TaskParameterInformation) for more information.

tasknameThe task name hint.

parameternameThe parameter name to match.

The task parameter informations mapped to their corresponding tasks.

public default Map<TaskName, ? extends TaskInformation> getTasks(String tasknamekeyword)

Gets information about tasks based on a hint keyword.

This method queries the information provider for task informations based on a hint task name keyword. The provider can interpret the keyword in any way it sees fit.

The returned map should be ordered based on the relevance of the related task. Implementations are recommended to use a map which keeps the insertion order, such as LinkedHashMap.

The hint keyword might be null in which case implementations should list as many tasks it can currently provide. In this case implementations are not required to list all task relations, only the ones it has information about. (I.e. there is no need to build a full index of all the tasks in a given implementation, as that could result in too big work. E.g. no need to retrieve all tasks from a repository, only return the ones it currently knows about.)

If the hint keyword is not null, then implementations should not return tasks which are not related to it. That is, it should properly filter the task informations based on the hint keyword.

tasknamekeywordThe task name hint keyword or null.

The informations for the related tasks.