blob: f3253cff6e6eba8765c3d429396884eacc738ec4 [file] [log] [blame]
// Copyright (c) 2014, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
/**
* Support for client code that needs to interact with the requests, responses
* and notifications that are part of the analysis server's wire protocol.
*/
import 'dart:convert' hide JsonDecoder;
import 'package:analysis_server/protocol/protocol_generated.dart';
import 'package:analysis_server/src/protocol/protocol_internal.dart';
export 'package:analyzer_plugin/protocol/protocol.dart' show Enum;
/**
* A notification that can be sent from the server about an event that occurred.
*
* Clients may not extend, implement or mix-in this class.
*/
class Notification {
/**
* The name of the JSON attribute containing the name of the event that
* triggered the notification.
*/
static const String EVENT = 'event';
/**
* The name of the JSON attribute containing the result values.
*/
static const String PARAMS = 'params';
/**
* The name of the event that triggered the notification.
*/
final String event;
/**
* A table mapping the names of notification parameters to their values, or
* `null` if there are no notification parameters.
*/
final Map<String, Object> params;
/**
* Initialize a newly created [Notification] to have the given [event] name.
* If [params] is provided, it will be used as the params; otherwise no
* params will be used.
*/
Notification(this.event, [this.params]);
/**
* Initialize a newly created instance based on the given JSON data.
*/
factory Notification.fromJson(Map json) {
return new Notification(json[Notification.EVENT],
json[Notification.PARAMS] as Map<String, Object>);
}
/**
* Return a table representing the structure of the Json object that will be
* sent to the client to represent this response.
*/
Map<String, Object> toJson() {
Map<String, Object> jsonObject = {};
jsonObject[EVENT] = event;
if (params != null) {
jsonObject[PARAMS] = params;
}
return jsonObject;
}
}
/**
* A request that was received from the client.
*
* Clients may not extend, implement or mix-in this class.
*/
class Request {
/**
* The name of the JSON attribute containing the id of the request.
*/
static const String ID = 'id';
/**
* The name of the JSON attribute containing the name of the request.
*/
static const String METHOD = 'method';
/**
* The name of the JSON attribute containing the request parameters.
*/
static const String PARAMS = 'params';
/**
* The name of the optional JSON attribute indicating the time (milliseconds
* since epoch) at which the client made the request.
*/
static const String CLIENT_REQUEST_TIME = 'clientRequestTime';
/**
* The unique identifier used to identify this request.
*/
final String id;
/**
* The method being requested.
*/
final String method;
/**
* A table mapping the names of request parameters to their values.
*/
final Map<String, Object> params;
/**
* The time (milliseconds since epoch) at which the client made the request
* or `null` if this information is not provided by the client.
*/
final int clientRequestTime;
/**
* Initialize a newly created [Request] to have the given [id] and [method]
* name. If [params] is supplied, it is used as the "params" map for the
* request. Otherwise an empty "params" map is allocated.
*/
Request(this.id, this.method,
[Map<String, Object> params, this.clientRequestTime])
: params = params ?? <String, Object>{};
/**
* Return a request parsed from the given json, or `null` if the [data] is
* not a valid json representation of a request. The [data] is expected to
* have the following format:
*
* {
* 'clientRequestTime': millisecondsSinceEpoch
* 'id': String,
* 'method': methodName,
* 'params': {
* paramter_name: value
* }
* }
*
* where both the parameters and clientRequestTime are optional.
*
* The parameters can contain any number of name/value pairs. The
* clientRequestTime must be an int representing the time at which the client
* issued the request (milliseconds since epoch).
*/
factory Request.fromJson(Map<String, Object> result) {
var id = result[Request.ID];
var method = result[Request.METHOD];
if (id is! String || method is! String) {
return null;
}
var time = result[Request.CLIENT_REQUEST_TIME];
if (time != null && time is! int) {
return null;
}
var params = result[Request.PARAMS];
if (params is Map || params == null) {
return new Request(id, method, params as Map<String, Object>, time);
} else {
return null;
}
}
/**
* Return a request parsed from the given [data], or `null` if the [data] is
* not a valid json representation of a request. The [data] is expected to
* have the following format:
*
* {
* 'clientRequestTime': millisecondsSinceEpoch
* 'id': String,
* 'method': methodName,
* 'params': {
* paramter_name: value
* }
* }
*
* where both the parameters and clientRequestTime are optional.
*
* The parameters can contain any number of name/value pairs. The
* clientRequestTime must be an int representing the time at which the client
* issued the request (milliseconds since epoch).
*/
factory Request.fromString(String data) {
try {
var result = json.decode(data);
if (result is Map) {
return new Request.fromJson(result as Map<String, dynamic>);
}
return null;
} catch (exception) {
return null;
}
}
@override
int get hashCode {
return id.hashCode;
}
@override
bool operator ==(Object other) {
return other is Request &&
id == other.id &&
method == other.method &&
clientRequestTime == other.clientRequestTime &&
_equalMaps(params, other.params);
}
/**
* Return a table representing the structure of the Json object that will be
* sent to the client to represent this response.
*/
Map<String, Object> toJson() {
Map<String, Object> jsonObject = <String, Object>{};
jsonObject[ID] = id;
jsonObject[METHOD] = method;
if (params.isNotEmpty) {
jsonObject[PARAMS] = params;
}
if (clientRequestTime != null) {
jsonObject[CLIENT_REQUEST_TIME] = clientRequestTime;
}
return jsonObject;
}
bool _equalLists(List first, List second) {
if (first == null) {
return second == null;
}
if (second == null) {
return false;
}
int length = first.length;
if (length != second.length) {
return false;
}
for (int i = 0; i < length; i++) {
if (!_equalObjects(first[i], second[i])) {
return false;
}
}
return true;
}
bool _equalMaps(Map first, Map second) {
if (first == null) {
return second == null;
}
if (second == null) {
return false;
}
if (first.length != second.length) {
return false;
}
for (var key in first.keys) {
if (!second.containsKey(key)) {
return false;
}
if (!_equalObjects(first[key], second[key])) {
return false;
}
}
return true;
}
bool _equalObjects(Object first, Object second) {
if (first == null) {
return second == null;
}
if (second == null) {
return false;
}
if (first is Map) {
if (second is Map) {
return _equalMaps(first, second);
}
return false;
}
if (first is List) {
if (second is List) {
return _equalLists(first, second);
}
return false;
}
return first == second;
}
}
/**
* An exception that occurred during the handling of a request that requires
* that an error be returned to the client.
*
* Clients may not extend, implement or mix-in this class.
*/
class RequestFailure implements Exception {
/**
* The response to be returned as a result of the failure.
*/
final Response response;
/**
* Initialize a newly created exception to return the given reponse.
*/
RequestFailure(this.response);
}
/**
* An object that can handle requests and produce responses for them.
*
* Clients may not extend, implement or mix-in this class.
*/
abstract class RequestHandler {
/**
* Attempt to handle the given [request]. If the request is not recognized by
* this handler, return `null` so that other handlers will be given a chance
* to handle it. Otherwise, return the response that should be passed back to
* the client.
*/
Response handleRequest(Request request);
}
/**
* A response to a request.
*
* Clients may not extend, implement or mix-in this class.
*/
class Response {
/**
* The [Response] instance that is returned when a real [Response] cannot
* be provided at the moment.
*/
static final Response DELAYED_RESPONSE = new Response('DELAYED_RESPONSE');
/**
* The name of the JSON attribute containing the id of the request for which
* this is a response.
*/
static const String ID = 'id';
/**
* The name of the JSON attribute containing the error message.
*/
static const String ERROR = 'error';
/**
* The name of the JSON attribute containing the result values.
*/
static const String RESULT = 'result';
/**
* The unique identifier used to identify the request that this response is
* associated with.
*/
final String id;
/**
* The error that was caused by attempting to handle the request, or `null` if
* there was no error.
*/
final RequestError error;
/**
* A table mapping the names of result fields to their values. Should be
* `null` if there is no result to send.
*/
Map<String, Object> result;
/**
* Initialize a newly created instance to represent a response to a request
* with the given [id]. If [_result] is provided, it will be used as the
* result; otherwise an empty result will be used. If an [error] is provided
* then the response will represent an error condition.
*/
Response(this.id, {Map<String, Object> result, this.error}) : result = result;
/**
* Create and return the `DEBUG_PORT_COULD_NOT_BE_OPENED` error response.
*/
Response.debugPortCouldNotBeOpened(Request request, dynamic error)
: this(request.id,
error: new RequestError(
RequestErrorCode.DEBUG_PORT_COULD_NOT_BE_OPENED, '$error'));
/**
* Initialize a newly created instance to represent the FILE_NOT_ANALYZED
* error condition.
*/
Response.fileNotAnalyzed(Request request, String file)
: this(request.id,
error: new RequestError(RequestErrorCode.FILE_NOT_ANALYZED,
'File is not analyzed: $file.'));
/**
* Initialize a newly created instance to represent the FORMAT_INVALID_FILE
* error condition.
*/
Response.formatInvalidFile(Request request)
: this(request.id,
error: new RequestError(RequestErrorCode.FORMAT_INVALID_FILE,
'Error during `${request.method}`: invalid file.'));
/**
* Initialize a newly created instance to represent the FORMAT_WITH_ERROR
* error condition.
*/
Response.formatWithErrors(Request request)
: this(request.id,
error: new RequestError(RequestErrorCode.FORMAT_WITH_ERRORS,
'Error during `edit.format`: source contains syntax errors.'));
/**
* Initialize a newly created instance based on the given JSON data.
*/
factory Response.fromJson(Map json) {
try {
Object id = json[Response.ID];
if (id is! String) {
return null;
}
Object error = json[Response.ERROR];
RequestError decodedError;
if (error is Map) {
decodedError = new RequestError.fromJson(
new ResponseDecoder(null), '.error', error);
}
Object result = json[Response.RESULT];
Map<String, Object> decodedResult;
if (result is Map) {
decodedResult = result as Map<String, Object>;
}
return new Response(id, error: decodedError, result: decodedResult);
} catch (exception) {
return null;
}
}
/**
* Initialize a newly created instance to represent the
* GET_ERRORS_INVALID_FILE error condition.
*/
Response.getErrorsInvalidFile(Request request)
: this(request.id,
error: new RequestError(RequestErrorCode.GET_ERRORS_INVALID_FILE,
'Error during `analysis.getErrors`: invalid file.'));
/**
* Initialize a newly created instance to represent the
* GET_IMPORTED_ELEMENTS_INVALID_FILE error condition.
*/
Response.getImportedElementsInvalidFile(Request request)
: this(request.id,
error: new RequestError(
RequestErrorCode.GET_IMPORTED_ELEMENTS_INVALID_FILE,
'Error during `analysis.getImportedElements`: invalid file.'));
/**
* Initialize a newly created instance to represent the
* GET_KYTHE_ENTRIES_INVALID_FILE error condition.
*/
Response.getKytheEntriesInvalidFile(Request request)
: this(request.id,
error: new RequestError(
RequestErrorCode.GET_KYTHE_ENTRIES_INVALID_FILE,
'Error during `analysis.getKytheEntries`: invalid file.'));
/**
* Initialize a newly created instance to represent the
* GET_NAVIGATION_INVALID_FILE error condition.
*/
Response.getNavigationInvalidFile(Request request)
: this(request.id,
error: new RequestError(
RequestErrorCode.GET_NAVIGATION_INVALID_FILE,
'Error during `analysis.getNavigation`: invalid file.'));
/**
* Initialize a newly created instance to represent the
* GET_REACHABLE_SOURCES_INVALID_FILE error condition.
*/
Response.getReachableSourcesInvalidFile(Request request)
: this(request.id,
error: new RequestError(
RequestErrorCode.GET_REACHABLE_SOURCES_INVALID_FILE,
'Error during `analysis.getReachableSources`: invalid file.'));
/**
* Initialize a newly created instance to represent the
* GET_SIGNATURE_INVALID_FILE error condition.
*/
Response.getSignatureInvalidFile(Request request)
: this(request.id,
error: new RequestError(RequestErrorCode.GET_SIGNATURE_INVALID_FILE,
'Error during `analysis.getSignature`: invalid file.'));
/**
* Initialize a newly created instance to represent the
* GET_SIGNATURE_INVALID_OFFSET error condition.
*/
Response.getSignatureInvalidOffset(Request request)
: this(request.id,
error: new RequestError(
RequestErrorCode.GET_SIGNATURE_INVALID_OFFSET,
'Error during `analysis.getSignature`: invalid offset.'));
/**
* Initialize a newly created instance to represent the
* GET_SIGNATURE_UNKNOWN_FUNCTION error condition.
*/
Response.getSignatureUnknownFunction(Request request)
: this(request.id,
error: new RequestError(
RequestErrorCode.GET_SIGNATURE_UNKNOWN_FUNCTION,
'Error during `analysis.getSignature`: unknown function.'));
/**
* Initialize a newly created instance to represent the
* IMPORT_ELEMENTS_INVALID_FILE error condition.
*/
Response.importElementsInvalidFile(Request request)
: this(request.id,
error: new RequestError(
RequestErrorCode.IMPORT_ELEMENTS_INVALID_FILE,
'Error during `edit.importElements`: invalid file.'));
/**
* Initialize a newly created instance to represent an error condition caused
* by an analysis.reanalyze [request] that specifies an analysis root that is
* not in the current list of analysis roots.
*/
Response.invalidAnalysisRoot(Request request, String rootPath)
: this(request.id,
error: new RequestError(RequestErrorCode.INVALID_ANALYSIS_ROOT,
"Invalid analysis root: $rootPath"));
/**
* Initialize a newly created instance to represent an error condition caused
* by a [request] that specifies an execution context whose context root does
* not exist.
*/
Response.invalidExecutionContext(Request request, String contextId)
: this(request.id,
error: new RequestError(RequestErrorCode.INVALID_EXECUTION_CONTEXT,
"Invalid execution context: $contextId"));
/**
* Initialize a newly created instance to represent the
* INVALID_FILE_PATH_FORMAT error condition.
*/
Response.invalidFilePathFormat(Request request, path)
: this(request.id,
error: new RequestError(RequestErrorCode.INVALID_FILE_PATH_FORMAT,
'Invalid file path format: $path'));
/**
* Initialize a newly created instance to represent an error condition caused
* by a [request] that had invalid parameter. [path] is the path to the
* invalid parameter, in Javascript notation (e.g. "foo.bar" means that the
* parameter "foo" contained a key "bar" whose value was the wrong type).
* [expectation] is a description of the type of data that was expected.
*/
Response.invalidParameter(Request request, String path, String expectation)
: this(request.id,
error: new RequestError(RequestErrorCode.INVALID_PARAMETER,
"Invalid parameter '$path'. $expectation."));
/**
* Initialize a newly created instance to represent an error condition caused
* by a malformed request.
*/
Response.invalidRequestFormat()
: this('',
error: new RequestError(
RequestErrorCode.INVALID_REQUEST, 'Invalid request'));
/**
* Initialize a newly created instance to represent the
* ORGANIZE_DIRECTIVES_ERROR error condition.
*/
Response.organizeDirectivesError(Request request, String message)
: this(request.id,
error: new RequestError(
RequestErrorCode.ORGANIZE_DIRECTIVES_ERROR, message));
/**
* Initialize a newly created instance to represent the
* REFACTORING_REQUEST_CANCELLED error condition.
*/
Response.refactoringRequestCancelled(Request request)
: this(request.id,
error: new RequestError(
RequestErrorCode.REFACTORING_REQUEST_CANCELLED,
'The `edit.getRefactoring` request was cancelled.'));
/**
* Initialize a newly created instance to represent the SERVER_ERROR error
* condition.
*/
factory Response.serverError(Request request, exception, stackTrace) {
RequestError error =
new RequestError(RequestErrorCode.SERVER_ERROR, exception.toString());
if (stackTrace != null) {
error.stackTrace = stackTrace.toString();
}
return new Response(request.id, error: error);
}
/**
* Initialize a newly created instance to represent the
* SORT_MEMBERS_INVALID_FILE error condition.
*/
Response.sortMembersInvalidFile(Request request)
: this(request.id,
error: new RequestError(RequestErrorCode.SORT_MEMBERS_INVALID_FILE,
'Error during `edit.sortMembers`: invalid file.'));
/**
* Initialize a newly created instance to represent the
* SORT_MEMBERS_PARSE_ERRORS error condition.
*/
Response.sortMembersParseErrors(Request request, int numErrors)
: this(request.id,
error: new RequestError(RequestErrorCode.SORT_MEMBERS_PARSE_ERRORS,
'Error during `edit.sortMembers`: file has $numErrors scan/parse errors.'));
/**
* Initialize a newly created instance to represent an error condition caused
* by a [request] that cannot be handled by any known handlers.
*/
Response.unknownRequest(Request request)
: this(request.id,
error: new RequestError(
RequestErrorCode.UNKNOWN_REQUEST, 'Unknown request'));
/**
* Initialize a newly created instance to represent an error condition caused
* by a [request] for a service that is not supported.
*/
Response.unsupportedFeature(String requestId, String message)
: this(requestId,
error: new RequestError(
RequestErrorCode.UNSUPPORTED_FEATURE, message));
/**
* Return a table representing the structure of the Json object that will be
* sent to the client to represent this response.
*/
Map<String, Object> toJson() {
Map<String, Object> jsonObject = <String, Object>{};
jsonObject[ID] = id;
if (error != null) {
jsonObject[ERROR] = error.toJson();
}
if (result != null) {
jsonObject[RESULT] = result;
}
return jsonObject;
}
}