YUKI Hiroshi
null+****@clear*****
Thu Feb 20 14:13:34 JST 2014
YUKI Hiroshi 2014-02-20 14:13:34 +0900 (Thu, 20 Feb 2014) New Revision: d95903fcce1db0f63fc1bf7f201b059910ec62c8 https://github.com/droonga/droonga.org/commit/d95903fcce1db0f63fc1bf7f201b059910ec62c8 Message: Update japanese version pages Modified files: ja/reference/plugin/adapter/index.md ja/reference/plugin/error/index.md ja/reference/plugin/matching-pattern/index.md ja/tutorial/plugin-development/adapter/index.md Modified: ja/reference/plugin/adapter/index.md (+190 -57) =================================================================== --- ja/reference/plugin/adapter/index.md 2014-02-20 14:12:55 +0900 (71a0855) +++ ja/reference/plugin/adapter/index.md 2014-02-20 14:13:34 +0900 (9df2da3) @@ -28,25 +28,21 @@ For example, here is a sample plugin named "foo" with an adapter: ~~~ruby require "droonga/plugin" -module Droonga - module Plugins - module FooPlugin - Plugin.registry.register("foo", self) - - class Adapter < Droonga::Adapter - # operations to configure this adapter - message.XXXXXX = XXXXXX - - def adapt_input(input_message) - # operations to modify incoming messages - input_message.XXXXXX = XXXXXX - end - - def adapt_output(output_message) - # operations to modify outgoing messages - output_message.XXXXXX = XXXXXX - end - end +module Droonga::Plugins::FooPlugin + Plugin.registry.register("foo", self) + + class Adapter < Droonga::Adapter + # operations to configure this adapter + XXXXXX = XXXXXX + + def adapt_input(input_message) + # operations to modify incoming messages + input_message.XXXXXX = XXXXXX + end + + def adapt_output(output_message) + # operations to modify outgoing messages + output_message.XXXXXX = XXXXXX end end end @@ -54,8 +50,8 @@ end Steps to define an adapter: - 1. Define a module for your plugin (ex. `Droonga::Plugin::FooPlugin`) and register it as a plugin. (required) - 2. Define an adapter class (ex. `Droonga::Plugin::FooPlugin::Adapter`) inheriting [`Droonga::Adapter`](#classes-Droonga-Adapter). (required) + 1. Define a module for your plugin (ex. `Droonga::Plugins::FooPlugin`) and register it as a plugin. (required) + 2. Define an adapter class (ex. `Droonga::Plugins::FooPlugin::Adapter`) inheriting [`Droonga::Adapter`](#classes-Droonga-Adapter). (required) 3. [Configure conditions to apply the adapter](#howto-configure). (required) 4. Define adaption logic for incoming messages as [`#adapt_input`](#classes-Droonga-Adapter-adapt_input). (optional) 5. Define adaption logic for outgoing messages as [`#adapt_output`](#classes-Droonga-Adapter-adapt_output). (optional) @@ -68,17 +64,19 @@ For more details, see also the [plugin development tutorial](../../../tutorial/p An adapter works like following: 1. The Droonga Engine starts. - * A global instance of the adapter class (ex. `Droonga::Plugin::FooPlugin::Adapter`) is created and it is registered. + * A global instance of the adapter class (ex. `Droonga::Plugins::FooPlugin::Adapter`) is created and it is registered. * The input pattern and the output pattern are registered. * The Droonga Engine starts to wait for incoming messages. 2. An incoming message is transferred from the Protocol Adapter to the Droonga Engine. Then, the adaption phase (for an incoming message) starts. - * The adapter's [`#adapt_input`](#classes-Droonga-Adapter-adapt_input) is called, if the message matches to the [input matching pattern](#config). + * The adapter's [`#adapt_input`](#classes-Droonga-Adapter-adapt_input) is called, if the message matches to the [input matching pattern](#config) of the adapter. * The method can modify the given incoming message, via [its methods](#classes-Droonga-InputMessage). 3. After all adapters are applied, the adaption phase for an incoming message ends, and the message is transferred to the next "planning" phase. 4. An outgoing message returns from the previous "collection" phase. Then, the adaption phase (for an outgoing message) starts. - * The adapter's [`#adapt_output`](#classes-Droonga-Adapter-adapt_output) is called, if the corresponding incoming message was processed by the adapter and the outgoing message matches to the [output matching pattern](#config). + * The adapter's [`#adapt_output`](#classes-Droonga-Adapter-adapt_output) is called, if the message meets following both requirements: + - It is originated from an incoming message which was processed by the adapter itself. + - It matches to the [output matching pattern](#config) of the adapter. * The method can modify the given outgoing message, via [its methods](#classes-Droonga-OutputMessage). 5. After all adapters are applied, the adaption phase for an outgoing message ends, and the outgoing message is transferred to the Protocol Adapter. @@ -86,35 +84,37 @@ 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]. +Any error raised from the adapter is handled by the Droonga Engine itself. See also [error handling][]. ## Configurations {#config} -`input_message.pattern` -: A [matching pattern] for incoming messages. - Only messages matched to the given patten are processed by [`#adapt_input`](#classes-Droonga-Adapter-adapt_input). - -`output_message.pattern` -: A [matching pattern] for outgoing messages. - Only messages matched to the given patten are processed by [`#adapt_output`](#classes-Droonga-Adapter-adapt_output). +`input_message.pattern` (optional, default=`nil`) +: A [matching pattern][] for incoming messages. + If no pattern (`nil`) is given, any message is regarded as "matched". +`output_message.pattern` (optional, default=`nil`) +: A [matching pattern][] for outgoing messages. + If no pattern (`nil`) is given, any message is regarded as "matched". +Note: On Droonga 0.9.9, they are named as `message.input_pattern` and `message.output_pattern` but changed to new configurations on Droonga 1.0.0, like above. If you write plugins for Droonga 0.9.9, you have to migrate it. ## Classes and methods {#classes} ### `Droonga::Adapter` {#classes-Droonga-Adapter} -This is the common base class of any adapter. Your plugin's adapter class must inherit the class. +This is the common base class of any adapter. Your plugin's adapter class must inherit this. #### `#adapt_input(input_message)` {#classes-Droonga-Adapter-adapt_input} -Receives an instance of [`Droonga::InputMessage`](#classes-Droonga-InputMessage) corresponding to an incoming message. +This method receives a [`Droonga::InputMessage`](#classes-Droonga-InputMessage) wrapped incoming message. +You can modify the incoming message via its methods. -By defualt this method does nothing, so you have to override it like following: +In this base class, this method is defined as just a placeholder and it does nothing. +To modify incoming messages, you have to override it by yours, like following: ~~~ruby -module FooPlugin +module Droonga::Plugins::QueryFixer class Adapter < Droonga::Adapter def adapt_input(input_message) input_message.body["query"] = "fixed query" @@ -125,60 +125,193 @@ end #### `#adapt_output(output_message)` {#classes-Droonga-Adapter-adapt_output} -Receives an instance of [`Droonga::OutputMessage`](#classes-Droonga-InputMessage) corresponding to an outgoing message. +This method receives a [`Droonga::OutputMessage`](#classes-Droonga-OutputMessage) wrapped outgoing message. +You can modify the outgoing message via its methods. -By defualt this method does nothing, so you have to override it like following: +In this base class, this method is defined as just a placeholder and it does nothing. +To modify outgoing messages, you have to override it by yours, like following: ~~~ruby -module FooPlugin +module Droonga::Plugins::ErrorConcealer class Adapter < Droonga::Adapter def adapt_output(output_message) - output_message.status_code = StatusCode::OK + output_message.status_code = Droonga::StatusCode::OK end end end ~~~ -### `Droonga::Plugin::Metadata::AdapterMessage` {#classes-Droonga-Plugin-Metadata-AdapterMessage} +### `Droonga::InputMessage` {#classes-Droonga-InputMessage} -(under construction) +#### `#command`, `#command=(command)` {#classes-Droonga-InputMessage-command} -#### `#input_pattern`, `#input_pattern=(pattern)` {#classes-Droonga-Plugin-Metadata-AdapterMessage-input_pattern} +This returns the `"type"` of the incoming message. -(under construction) +You can override it by assigning a new string value, like: -#### `#output_pattern`, `#output_pattern=(pattern)` {#classes-Droonga-Plugin-Metadata-AdapterMessage-output_pattern} +~~~ruby +module Droonga::Plugins::MySearch + class Adapter < Droonga::Adapter + input_message.pattern = ["type", :equal, "my-search"] -(under construction) + def adapt_input(input_message) + p input_message.command + # => "my-search" + # This message will be handled by a plugin + # for the custom "my-search" command. + + input_message.command = "search" + + p input_message.command + # => "search" + # The messge type (command) is changed. + # This message will be handled by the "search" plugin, + # as a regular search request. + end + end +end +~~~ -### `Droonga::InputMessage` {#classes-Droonga-InputMessage} +#### `#body`, `#body=(body)` {#classes-Droonga-InputMessage-body} -(under construction) +This returns the `"body"` of the incoming message. -#### `#command`, `#command=(command)` {#classes-Droonga-InputMessage-command} +You can override it by assigning a new value, partially or fully. For example: -(under construction) +~~~ruby +module Droonga::Plugins::MinimumLimit + class Adapter < Droonga::Adapter + input_message.pattern = ["type", :equal, "search"] -#### `#body`, `#body=(body)` {#classes-Droonga-InputMessage-body} + MAXIMUM_LIMIT = 10 + + def adapt_input(input_message) + input_message.body["queries"].each do |name, query| + query["output"] ||= {} + query["output"]["limit"] ||= MAXIMUM_LIMIT + query["output"]["limit"] = [query["output"]["limit"], MAXIMUM_LIMIT].min + end + # Now, all queries have "output.limit=10". + end + end +end +~~~ -(under construction) +Another case: -### `Droonga::OutputMessage` {#classes-Droonga-OutputMessage} +~~~ruby +module Droonga::Plugins::MySearch + class Adapter < Droonga::Adapter + input_message.pattern = ["type", :equal, "my-search"] + + def adapt_input(input_message) + # Extract the query string from the custom command. + query_string = input_message["body"]["query"] + + # Construct internal search request for the "search" command. + input_message.command = "search" + input_message.body = { + "queries" => { + "source" => "Store", + "condition" => { + "query" => query_string, + "matchTo" => ["name"], + }, + "output" => { + "elements" => ["records"], + "limit" => 10, + }, + }, + } + # Now, both "type" and "body" are completely replaced. + end + end +end +~~~ -(under construction) +### `Droonga::OutputMessage` {#classes-Droonga-OutputMessage} #### `#status_code`, `#status_code=(status_code)` {#classes-Droonga-OutputMessage-status_code} -(under construction) +This returns the `"statusCode"` of the outgoing message. + +You can override it by assigning a new status code. For example: + +~~~ruby +module Droonga::Plugins::ErrorConcealer + class Adapter < Droonga::Adapter + input_message.pattern = ["type", :equal, "search"] + + def adapt_output(output_message) + unless output_message.status_code == StatusCode::InternalServerError + output_message.status_code = Droonga::StatusCode::OK + output_message.body = {} + output_message.errors = nil + # Now any internal server error is ignored and clients + # receive regular responses. + end + end + end +end +~~~ #### `#errors`, `#errors=(errors)` {#classes-Droonga-OutputMessage-errors} -(under construction) +This returns the `"errors"` of the outgoing message. + +You can override it by assigning new error information, partially or fully. For example: + +~~~ruby +module Droonga::Plugins::ErrorExporter + class Adapter < Droonga::Adapter + input_message.pattern = ["type", :equal, "search"] + + def adapt_output(output_message) + output_message.errors.delete(secret_database) + # Delete error information from secret database + + output_message.body["errors"] = { + "records" => output_message.errors.collect do |database, error| + { + "database" => database, + "error" => error + } + end, + } + # Convert error informations to a fake search result named "errors". + end + end +end +~~~ #### `#body`, `#body=(body)` {#classes-Droonga-OutputMessage-body} -(under construction) +This returns the `"body"` of the outgoing message. + +You can override it by assigning a new value, partially or fully. For example: + +~~~ruby +module Droonga::Plugins::SponsoredSearch + class Adapter < Droonga::Adapter + input_message.pattern = ["type", :equal, "search"] + + def adapt_output(output_message) + output_message.body.each do |name, result| + next unless result["records"] + result["records"].unshift(sponsored_entry) + end + # Now all search results include sponsored entry. + end + def sponsored_entry + { + "title"=> "SALE!", + "url"=> "http://..." + } + end + end +end +~~~ [matching pattern]: ../matching-pattern/ Modified: ja/reference/plugin/error/index.md (+5 -4) =================================================================== --- ja/reference/plugin/error/index.md 2014-02-20 14:12:55 +0900 (d475214) +++ ja/reference/plugin/error/index.md 2014-02-20 14:13:34 +0900 (668cc13) @@ -20,28 +20,29 @@ layout: ja 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. +If you want formatted error information to be returned, then rescue errors and raise your custom errors inheriting `Droonga::ErrorMessage::BadRequest` or `Droonga::ErrorMessage::InternalServerError` instead of raw errors. +(By the way, they are already included to the base class of plugins so you can define your custom errors easily like: `class CustomError < BadRequest`) ## 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` +### `Droonga::ErrorMessage::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` +### `Droonga::ErrorMessage::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` +### `Droonga::ErrorMessage::InternalServerError` Means other unknown error, ex. timed out, file I/O error, and so on. For example: Modified: ja/reference/plugin/matching-pattern/index.md (+158 -8) =================================================================== --- ja/reference/plugin/matching-pattern/index.md 2014-02-20 14:12:55 +0900 (1dbb763) +++ ja/reference/plugin/matching-pattern/index.md 2014-02-20 14:13:34 +0900 (75f2128) @@ -48,7 +48,7 @@ This matches to messages like: } } -Not matches to: +Doesn't match to: { "type": "add.result", @@ -62,7 +62,7 @@ Not matches to: pattern = [ ["type", :equal, "table_create"], :or, - ["type", :equal, "column_create"] + ["body.success", :equal, true] ] This matches to both: @@ -77,16 +77,166 @@ and: { "type": "column_create", ... + "body": { + "success": true + } } ## Syntax {#syntax} +There are two typeos of matching patterns: "basic pattern" and "nested pattern". + +### Basic pattern {#syntax-basic} + +#### Structure {#syntax-basic-structure} + +A basic pattern is described as an array including 2 or more elements, like following: + + ["type", :equal, "search"] + + * The first element is a *target path*. It means the location of the information to be checked, in the [message][]. + * The second element is an *operator*. It means how the information specified by the target path should be checked. + * The third element is an *argument for the oeprator*. It is a primitive value (string, numeric, or boolean) or an array of values. Some operators require no argument. + +#### Target path {#syntax-basic-target-path} + +The target path is specified as a string, like: + + "body.success" + +The matching mechanism of the Droonga Engine interprets it as a dot-separated list of *path components*. +A path component represents the property in the message with same name. +So, the example above means the location: + + { + "body": { + "success": <target> + } + } + + + + +#### Avialable operators {#syntax-basic-operators} + +The operator is specified as a symbol. + +`:equal` +: Returns `true`, if the target value is equal to the given value. Otherwise `false`. + For example, + + ["type", :equal, "search"] + + The pattern above matches to a message like following: + + { + "type": "search", + ... + } + +`:in` +: Returns `true`, if the target value is in the given array of values. Otherwise `false`. + For example, + + ["type", :in, ["search", "select"]] + + The pattern above matches to a message like following: + + { + "type": "select", + ... + } + + But it doesn't match to: + + { + "type": "find", + ... + } + +`:include` +: Returns `true` if the target array of values includes the given value. Otherwise `false`. + In other words, this is the opposite of the `:in` operator. + For example, + + ["body.tags", :include, "News"] + + The pattern above matches to a message like following: + + { + "type": "my.notification", + "body": { + "tags": ["News", "Groonga", "Droonga", "Fluentd"] + } + } + +`:exist` +: Returns `true` if the target exists. Otherwise `false`. + For example, + + ["body.comments", :exist, "News"] + + The pattern above matches to a message like following: + + { + "type": "my.notification", + "body": { + "title": "Hello!", + "comments": [] + } + } + + But it doesn't match to: + + { + "type": "my.notification", + "body": { + "title": "Hello!" + } + } + +`:start_with` +: Returns `true` if the target string value starts with the given string. Otherwise `false`. + For example, + + ["body.path", :start_with, "/archive/"] + + The pattern above matches to a message like following: + + { + "type": "my.notification", + "body": { + "path": "/archive/2014/02/28.html" + } + } + + +### Nested pattern {#syntax-nested} + +#### Structure {#syntax-nested-structure} + +A nested pattern is described as an array including 3 elements, like following: + + [ + ["type", :equal, "table_create"], + :or, + ["type", :equal, "column_create"] + ] + + * The first and the third elements are patterns, basic or nested. (In other words, you can nest patterns recursively.) + * The second element is a *logical operator*. + +#### Avialable operators {#syntax-nested-operators} + +`:and` +: Returns `true` if both given patterns are evaluated as `true`. Otherwise `false`. + +`:or` +: Returns `true` if one of given patterns (the first or the third element) is evaluated as `true`. Otherwise `false`. + + + - * `PATTERN` = [`TARGET_PATH`, `OPERATOR`, `ARGUMENTS*`] - * `PATTERN` = [`PATTERN`, `LOGICAL_OPERATOR`, `PATTERN`] - * `TARGET_PATH` = `"COMPONENT(.COMPONENT)*"` - * `OPERATOR` = `:equal`, `:in`, `:include`, `:exist`, `:start_with` - * `ARGUMENTS` = `OBJECT_DEFINED_IN_JSON*` - * `LOGICAL_OPERATOR` = `:or` + [message]:../../message/ Modified: ja/tutorial/plugin-development/adapter/index.md (+28 -4) =================================================================== --- ja/tutorial/plugin-development/adapter/index.md 2014-02-20 14:12:55 +0900 (21c9e7e) +++ ja/tutorial/plugin-development/adapter/index.md 2014-02-20 14:13:34 +0900 (8e24be0) @@ -199,7 +199,7 @@ lib/droonga/plugins/sample-logger.rb: Plugin.registry.register("sample-logger", self) class Adapter < Droonga::Adapter - message.input_pattern = ["type", :equal, "search"] + input_message.pattern = ["type", :equal, "search"] def adapt_input(input_message) $log.info("SampleLoggerPlugin::Adapter", :message => input_message) @@ -209,6 +209,15 @@ lib/droonga/plugins/sample-logger.rb: (snip) ~~~ +The line beginning with `input_message.pattern` is a configuration. +This example defines a plugin for any incoming message with `"type":"search"`. +See the [reference manual's configuration section](../../../reference/plugin/adapter/#config) + +(Note: `input_message.pattern` is for Droonga 1.0.0 and later. On Droonga 0.9.9, you have to use a deprecated configuration `message.input_pattern` instead.) + +The method `adapt_input` is called for every incoming message matching to the pattern. +The argument `input_message` is a wrapped version of the incoming message. + Restart fluentd: ~~~ @@ -255,7 +264,9 @@ This shows the message is received by our `SampleLoggerPlugin::Adapter` and then ### Modify messages with the plugin -Suppose that we want to restrict the number of records returned in the response, say `1`. What we need to do is set `limit` to be `1` for every request. Update plugin like below: +Suppose that we want to restrict the number of records returned in the response, say `1`. +What we need to do is set `limit` to be `1` for every request. +Update plugin like below: lib/droonga/plugins/sample-logger.rb: @@ -268,6 +279,9 @@ lib/droonga/plugins/sample-logger.rb: (snip) ~~~ +Like above, you can modify the incoming message via methods of the argument `input_message`. +See the [reference manual for the message class](../../../reference/plugin/adapter/#classes-Droonga-InputMessage). + Restart fluentd: ~~~ @@ -332,6 +346,8 @@ lib/droonga/plugins/sample-logger.rb: Plugin.registry.register("sample-logger", self) class Adapter < Droonga::Adapter + (snip) + def adapt_output(output_message) $log.info("SampleLoggerPlugin::Adapter", :message => output_message) end @@ -340,6 +356,9 @@ lib/droonga/plugins/sample-logger.rb: (snip) ~~~ +The method `adapt_output` is called only for outgoing messages triggered by incoming messages processed by the plugin itself. +See the [reference manual for plugin developers](../../../reference/plugin/adapter/) for more details. + ### Run Let's restart fluentd: @@ -404,6 +423,9 @@ lib/droonga/plugins/sample-logger.rb: (snip) ~~~ +Like above, you can modify the outgoing message via methods of the argument `output_message`. +See the [reference manual for the message class](../../../reference/plugin/adapter/#classes-Droonga-OutputMessage). + Restart fluentd: ~~~ @@ -472,7 +494,7 @@ module Droonga Plugin.registry.register("store-search", self) class Adapter < Droonga::Adapter - message.input_pattern = ["type", :equal, "storeSearch"] + input_message.pattern = ["type", :equal, "storeSearch"] def adapt_input(input_message) $log.info("StoreSearchPlugin::Adapter", :message => input_message) @@ -514,6 +536,8 @@ module Droonga end ~~~ +(Note: `input_message.pattern` is for Droonga 1.0.0 and later. On Droonga 0.9.9, you have to use a deprecated configuration `message.input_pattern` instead.) + Then update catalog.json to activate the plugin. Remove the `sample-logger` plugin previously created. catalog.json: @@ -662,7 +686,7 @@ In the way just described, we can use adapter to implement the application speci ## まとめ -We have learned how to create an addon working around the adaption phase, how to receive and modify messages, both of incoming and outgoing. +We have learned how to create an addon working around the adaption phase, how to receive and modify messages, both of incoming and outgoing. See also the [reference manual](../../../reference/plugin/adapter/) for more details. [basic tutorial]: ../../basic/ -------------- next part -------------- HTML����������������������������...Download