YUKI Hiroshi
null+****@clear*****
Mon Feb 17 18:58:31 JST 2014
YUKI Hiroshi 2014-02-17 18:58:31 +0900 (Mon, 17 Feb 2014) New Revision: 2a3dbfc6aced1beabbd9e9d64e81512c49f099b7 https://github.com/droonga/droonga.org/commit/2a3dbfc6aced1beabbd9e9d64e81512c49f099b7 Message: Add documentation about error handling in plugins Added files: reference/plugin/error/index.md Modified files: reference/plugin/adapter/index.md reference/plugin/index.md Modified: reference/plugin/adapter/index.md (+3 -10) =================================================================== --- reference/plugin/adapter/index.md 2014-02-17 18:29:46 +0900 (d1d1f32) +++ reference/plugin/adapter/index.md 2014-02-17 18:58:31 +0900 (3cad916) @@ -77,6 +77,8 @@ As described above, the Droonga Engine creates only one global instance of the a You should not keep stateful information for a pair of incoming and outgoing messages as an instance variable of the adapter. Instead, you should give stateful information as a part of the incoming message body, and receive it from the body of the corresponding outgoing message. +Any error raised from the adapter is handled by the Droonga Engine itself. See also [error handling]. + ## Configurations {#config} @@ -89,16 +91,6 @@ Instead, you should give stateful information as a part of the incoming message Only messages matched to the given patten are processed by [`#adapt_output`](#classes-Droonga-Adapter-adapt_output). -## Error handling {#error} - -### Errors on the adaption phase {#error-adaption} - -(TBD) - -### Errors on other phases {#error-others} - -(TBD) - ## Classes and methods {#classes} @@ -181,3 +173,4 @@ end [matching pattern]: ../matching-pattern/ + [error handling]: ../error/ Added: reference/plugin/error/index.md (+60 -0) 100644 =================================================================== --- /dev/null +++ reference/plugin/error/index.md 2014-02-17 18:58:31 +0900 (990642b) @@ -0,0 +1,60 @@ +--- +title: Error handling in plugins +layout: en +--- + +* TOC +{:toc} + + +## Abstract {#abstract} + +Any unhandled error raised from a plugin is returned as an [error response][] for the corresponding incoming message, with the status code `500` (means "internal error"). + +If you want formatted error information to be returned, then rescue errors and raise your custom errors inheriting `Droonga::MessageProcessingError` instead of raw errors. + + +## Built-in error classes {#builtin-errors} + +There are some pre-defined error classes used by built-in plugins and the Droonga Engine itself. + +### `Droonga::NotFound` + +Means an error which the specified resource is not found in the dataset or any source. For example: + + # the second argument means "details" of the error. (optional) + raise Droonga::NotFound.new("#{name} is not found!", :elapsed_time => elapsed_time) + +### `Droonga::BadRequest` + +Means any error originated from the incoming message itself, ex. syntax error, validation error, and so on. For example: + + # the second argument means "details" of the error. (optional) + raise Droonga::NotFound.new("Syntax error in #{query}!", :detail => detail) + +### `Droonga::MessageProcessingError` + +Means other unknown error, ex. timed out, file I/O error, and so on. For example: + + # the second argument means "details" of the error. (optional) + raise Droonga::MessageProcessingError.new("busy!", :elapsed_time => elapsed_time) + + +## Built-in status codes {#builtin-status-codes} + +You should use following or other status codes as [a matter of principle](../../message/#error-status). + +`Droonga::StatusCode::OK` +: Equals to `200`. + +`Droonga::StatusCode::NOT_FOUND` +: Equals to `404`. + +`Droonga::StatusCode::BAD_REQUEST` +: Equals to `400`. + +`Droonga::StatusCode::INTERNAL_ERROR` +: Equals to `500`. + + + [error response]: ../../message/#error Modified: reference/plugin/index.md (+1 -0) =================================================================== --- reference/plugin/index.md 2014-02-17 18:29:46 +0900 (237219c) +++ reference/plugin/index.md 2014-02-17 18:58:31 +0900 (5080035) @@ -9,3 +9,4 @@ See also the [plugin development tutorial](../../tutorial/plugin-development/). * [API set for the adaption phase](adapter/) * [API set for the handling phase](handler/) * [Matching pattern for messages](matching-pattern/) + * [Error handling](error/) -------------- next part -------------- HTML����������������������������...Download