From: paul Date: December 17 2005 12:07am Subject: svn commit - mysqldoc@docsrva: r578 - in trunk: . refman-4.1 refman-5.1 refman-common List-Archive: http://lists.mysql.com/commits/208 Message-Id: <200512170007.jBH07nhY014386@docsrva.mysql.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Author: paul Date: 2005-12-17 01:07:46 +0100 (Sat, 17 Dec 2005) New Revision: 578 Log: r4856@frost: paul | 2005-12-16 18:06:43 -0600 Plugin interface. Modified: trunk/ trunk/refman-4.1/manual.xml trunk/refman-5.1/extending-mysql.xml trunk/refman-common/titles.en.ent Property changes on: trunk ___________________________________________________________________ Name: svk:merge - b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:4807 bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:1694 + b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:4856 bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:1694 Modified: trunk/refman-4.1/manual.xml =================================================================== --- trunk/refman-4.1/manual.xml 2005-12-16 21:02:03 UTC (rev 577) +++ trunk/refman-4.1/manual.xml 2005-12-17 00:07:46 UTC (rev 578) @@ -18,8 +18,8 @@ - This is the MySQL Reference Manual. It documents MySQL 3.23 to - MySQL ¤t-version;. + This is the MySQL Reference Manual. It documents MySQL 3.23 + through MySQL ¤t-version;. Modified: trunk/refman-5.1/extending-mysql.xml =================================================================== --- trunk/refman-5.1/extending-mysql.xml 2005-12-16 21:02:03 UTC (rev 577) +++ trunk/refman-5.1/extending-mysql.xml 2005-12-17 00:07:46 UTC (rev 578) @@ -488,26 +488,32 @@ adding - - Also to mention: Describe the interface functions. - - - MySQL 5.1 and up provides a plugin interface that can be used to - add new functions to the server. This interface is intended to be - the successor to the older user-defined function (UDF) interface. - The plugin interface eventually will include an API for creating - UDFs, and it is intended this plugin UDF API will replace the - older non-plugin UDF API. After that point, it will be possible - for UDFs to be revised for use as plugin UDFs so that they can - take advantage of the better security and versioning capabilities - of the plugin API. Eventually, support for the older UDF API will - be phased out. + MySQL 5.1 and up supports a plugin API that allows the loading and + unloading of server components at runtime, without restarting the + server. Currently, the plugin API supports creation of full-text + parser plugins. Such a plugin can be used to replace or augment + the built-in full-text parser. For example, a plugin can parse + text into words using rules that differ from the rules used by the + built-in parser. This could be useful if you need to parse text + with different characteristics than those expected by the built-in + parser. + The plugin interface is intended as the successor to the older + user-defined function (UDF) interface. The plugin interface + eventually will include an API for creating UDFs, and it is + intended this plugin UDF API will replace the older non-plugin UDF + API. After that point, it will be possible for UDFs to be revised + for use as plugin UDFs so that they can take advantage of the + better security and versioning capabilities of the plugin API. + Eventually, support for the older UDF API will be phased out. + + + The plugin interface requires the plugin table in the mysql database. This table is created as part of the MySQL installation process. If you are upgrading from @@ -516,19 +522,333 @@ this table. See . - - A plugin contains code that becomes part of the running server, so - when you write a plugin, you are bound by any and all constraints - that otherwise apply to writing server code. For example, you may - have problems if you attempt to use functions from the - libstdc++ library. Note that these constraints - may change in future versions of the server, so it is possible - that server upgrades will require revisions to plugins that were - originally written for older servers. For information about these - constraints, see and - . - +
+ &title-plugin-api-characteristics; + + + In some respects, the plugin API is similar to the older + user-defined function (UDF) API that it supercedes, but the + plugin API has several advantages over the older interface: + + + + + + + The plugin framework is extendable to accommodate different + kinds of plugins. + + + + Some aspects of the plugin API are common to all types of + plugins, but the API also allows for type-specific interface + elements so that different types of plugins can be created. + A plugin with one purpose can have an interface most + appropriate to its own requirements and not the requirements + of some other plugin type. + + + + Although only the interface for full-text parser plugins is + implemented currently, others can be added, such as an + interface for UDF plugins. + + + + + + The plugin API includes versioning information. + + + + The version information included in the plugin API enables a + plugin library and each plugin that it contains to be + self-identifying with respect to the API version that was + used when the library was built. If the API changes over + time, the version numbers will change, but a server can + examine a given plugin library's version information to + determine whether it supports the plugins in the library. + + + + There are two types of version numbers. The first is the + version for the general plugin framework itself. Each plugin + library includes this kind of version number. The second + type of version applies to individual plugins. Each specific + type of plugin has a version for its interface, so each + plugin in a library has a type-specific version number. For + example, library containing a full-text parsing plugin has a + general plugin API version number, and the plugin has a + version number for the full-text plugin interface. + + + + + + Plugin security is improved relative to the UDF interface. + + + + The older interface for writing non-plugin UDFs allowed + libraries to be loaded from any directory searched by the + system's dynamic linker, and the symbols that identified the + UDF library were relatively non-specific. The newer rules + are more strict. A plugin library must be installed in a + specific dedicated directory for which the location is + controlled by the server and cannot be changed at runtime. + Also, the library must contain specific symbols that + identify it as a plugin library. The server will not load + something as a plugin if it was not built as a plugin. + + + + The newer plugin interface eliminates the security issues of + the older UDF interface. When a UDF plugin type is + implemented, that will allow non-plugin UDFs to be brought + into the plugin framework and the older interface will be + phased out. + + + + + + + The plugin implementation includes the following components: + + + + Source files (the locations given indicate where the files are + found in a MySQL source distribution): + + + + + + + include/plugin.h exposes the public + plugin API. This file should be examined by anyone who wants + to write a plugin library. + + + + + + sql/sql_plugin.h and + sql/sql_plugin.cc comprise the internal + plugin implementation. These files need not be consulted by + plugin writers. They may be of interest for those who want + to know more about how the server handles plugins. + + + + + + + System table: + + + + + + + The plugin table in the + mysql database lists each installed + plugin and is required for plugin use. For new MySQL + installations, this table is created during the installation + process. If you are upgrading from a version older than + MySQL 5.1, you should run + mysql_fix_privilege_tables to update your + system tables and create the plugin + table. + + + + + + + SQL statements: + + + + + + + INSTALL PLUGIN registers a plugin in the + plugin table and loads the plugin code. + + + + + + UNINSTALL PLUGIN unregisters a plugin + from the plugin table and unloads the + plugin code. + + + + + + The WITH PARSER clause for full-text + index creation associates a full-text parser plugin with a + given FULLTEXT index. + + + + + + + System variable: + + + + + + + plugin_dir indicates the location of the + directory where all plugins (and UDFs) must be installed. + The value of this variable can be specified at server + startup with a + + option. + + + + + +
+ +
+ + &title-plugin-full-text-plugins; + + + MySQL has a built-in parser that it uses by default for + full-text operations (parsing text to be indexed, or parsing a + query string to determine the terms to be used for a search). + For full-text processing, parsing means + extracting words from text or a query string based on rules that + define which character sequences make up a word and where word + boundaries lie. + + + + When parsing for indexing purposes, the parser passes each word + to the server, which adds it to a full-text index. When parsing + a query string, the parser passes each word to the server, which + accumulates the words for use in a search. + + + + The parsing properties of the built-in full-text parser are + described in . These properties + include rules for determining how to extract words from text. + The parser is influenced by certain system variables such as + ft_min_word_len and + ft_max_word_len that cause words shorter or + longer to be excluded, and by the stopword list that identifies + common words to be ignored. + + + + The plugin API enables you to provide a full-text parser of your + own so that you have control over the basic duties of a parser. + A parser plugin can operate in either of two roles: + + + + + + + The plugin can replace the built-in parser. In this role, + the plugin reads the input to be parsed, splits it up into + words, and passes the words to the server (either for + indexing or for word accumulation). + + + + One reason to use a parser this way is that you need to use + different rules from those of the built-in parser for + determining how to split up input into words. For example, + the built-in parser considers the text + case-sensitive to consist of two words + case and sensitive, whereas an + application might need to treat the text as a single word. + + + + + + The plugin can act in conjunction with the built-in parser + by serving as a front end for it. In this role, the plugin + extracts text from the input and passes the text to the + parser, which splits up the text into words using its normal + parsing rules. + + + + One reason to use a parser this way is that you need to + index content such as PDF documents, XML documents, or + .doc files. The built-in parser is not + intended for those types of input but a plugin can pull out + the text from these input sources and pass it to the + built-in parser. + + + + + + + It is also possible for a parser plugin to operate in both + roles. That is, it could extract text from non-plaintext input + (the front-end role), and also parse the text into words (thus + replacing the built-in parser). + + + + A full-text plugin is associated with full-text indexes on a + per-index basis. That is, when you install a parser plugin + initially, that does not cause it to be used for any full-text + operations. It simply becomes available. For example, a + full-text parser plugin becomes available to be named in a + WITH PARSER clause when creating individual + FULLTEXT indexes. To create such an index at + table-creation time, do this: + + + +CREATE TABLE t +( + doc CHAR(255), + FULLTEXT INDEX (doc) WITH PARSER my_parser +); + + + + Or you can add the index after the table has been created: + + + +ALTER TABLE t ADD FULLTEXT INDEX (doc) WITH PARSER my_parser; + + + + The only SQL change for associating the parser with the index is + the WITH PARSER clause. Searches are + specified as before, with no changes needed for queries. + + + + When you associate a parser plugin with a + FULLTEXT index, the plugin is required for + using the index. If the parser plugin is dropped, any index + associated with it becomes unusable. Any attempt to use it a + table for which a plugin is not available results in an error, + although DROP TABLE is still possible. + + +
+
&title-install-plugin; @@ -693,10 +1013,9 @@ plugin_name must be the name of some - plugin that is listed in the - mysql.plugin table. The server - executes the plugin's termination (deinit()) - function. It also removes the row for the plugin from the + plugin that is listed in the mysql.plugin + table. The server executes the plugin's deinitialization + function and removes the row for the plugin from the mysql.plugin table, so that subsequent server restarts will not load and initialize the plugin. UNINSTALL PLUGIN does not remove the plugin's @@ -715,23 +1034,1131 @@ Plugin removal has implications for the use of associated tables. For example, if a full-text parser plugin is associated with a FULLTEXT index on the table, - uninstalling the plugin makes the table unusable. The table - cannot be opened, so you cannot drop the index for which the - plugin is used. This means that uninstalling a plugin is - something to do with care unless you do not care about the table - contents. If you are uninstalling a plugin with no intention of - reinstalling it later (for example, to update it with a new - version), and you care about the table contents, you should dump - the table with mysqldump and remove the - WITH PARSER clause from the dumped - CREATE TABLE statement so that you can reload - the table later. If you do not care about the table, - DROP TABLE can be used even if plugins - associated with the table are missing. + uninstalling the plugin makes the table unusable. Any attempt to + access the table results in an error. The table cannot even be + opened, so you cannot drop an index for which the plugin is + used. This means that uninstalling a plugin is something to do + with care unless you do not care about the table contents. If + you are uninstalling a plugin with no intention of reinstalling + it later (for example, to update it with a new version), and you + care about the table contents, you should dump the table with + mysqldump and remove the WITH + PARSER clause from the dumped CREATE + TABLE statement so that you can reload the table + later. If you do not care about the table, DROP + TABLE can be used even if plugins associated with the + table are missing.
+
+ + &title-plugin-writing; + + + This section describes the general and type-specific parts of + the plugin API. It also provides a step-by-step guide to + creating a plugin library. + + + + You can write plugins in C or C++. Plugins are loaded and + unloaded dynamically, so your operating system must support + dynamic loading and you must have compiled + mysqld dynamically (not statically). + + + + A plugin contains code that becomes part of the running server, + so when you write a plugin, you are bound by any and all + constraints that otherwise apply to writing server code. For + example, you may have problems if you attempt to use functions + from the libstdc++ library. Note that these + constraints may change in future versions of the server, so it + is possible that server upgrades will require revisions to + plugins that were originally written for older servers. For + information about these constraints, see + and + . + + +
+ + &title-plugin-api-general; + + + Every plugin must have a general plugin declaration. The + declaration corresponds to the + st_mysql_plugin structure in the + plugin.h file: + + + +struct st_mysql_plugin +{ + int type; /* the plugin type (a MYSQL_XXX_PLUGIN value) */ + void *info; /* pointer to type-specific plugin descriptor */ + const char *name; /* plugin name */ + const char *author; /* plugin author (for SHOW PLUGINS) */ + const char *descr; /* general descriptive text (for SHOW PLUGINS ) */ + int (*init)(void); /* the function to invoke when plugin is loaded */ + int (*deinit)(void); /* the function to invoke when plugin is unloaded */ +}; + + + + The st_mysql_plugin structure is common to + every type of plugin. Its members are used as follows: + + + + + + + type + + + + The plugin type. This must be one of the plugin-type + values from plugin.h. For a full-text + parser plugin, the type value is + MYSQL_FTPARSER_PLUGIN. + + + + + + info + + + + A pointer to the descriptor for the plugin. Unlike the + general plugin declaration structure, this descriptor's + structure depends on the particular type of plugin. Each + descriptor has a version number that indicates the API + version for that type of plugin, plus any other members + needed. The descriptor for full-text plugins is described + in . + + + + + + name + + + + The plugin name. This is the name that will be listed in + the plugin table and by which you refer + to the plugin in SQL statements such as INSTALL + PLUGIN and UNINSTALL PLUGIN. + + + + + + author + + + + The plugin author. This can be whatever you like. + + + + + + desc + + + + A general description of the plugin. This can be whatever + you like. + + + + + + init + + + + A once-only initialization function. This is executed when + the plugin is loaded, which happens for INSTALL + PLUGIN or, for plugins listed in the + plugin table, at server startup. The + function takes no arguments. It returns 0 for success and + 1 for failure. + + + + + + deinit + + + + A once-only deinitialization function. This is executed + when the plugin is unloaded, which happens for + UNINSTALL PLUGIN or, for plugins listed + in the plugin table, at server + shutdown. The function takes no arguments. It returns 0 + for success and 1 for failure. + + + + + + + The init and deinit + functions in the general plugin declaration are invoked only + when loading and unloading the plugin. They have nothing to do + with use of the plugin such as happens when a SQL statement + causes the plugin to be invoked. + + + + If an init or deinit + function is unneeded for a plugin, it can be specified as 0 in + the st_mysql_plugin structure. + + +
+ +
+ + &title-plugin-api-type-specific; + + + In the st_mysql_plugin structure that + defines a plugin's general declaration, the + info member points to a type-specific + plugin descriptor. For a full-text parser plugin, the + descriptor corresponds to the + st_mysql_ftparser structure in the + plugin.h file: + + + +struct st_mysql_ftparser +{ + int interface_version; + int (*parse)(MYSQL_FTPARSER_PARAM *param); + int (*init)(MYSQL_FTPARSER_PARAM *param); + int (*deinit)(MYSQL_FTPARSER_PARAM *param); +}; + + + + As shown by the structure definition, the descriptor has a + version number + (MYSQL_FTPARSER_INTERFACE_VERSION for + full-text parser plugins) and contains pointers to three + functions. Each each of these functions should point to a + function or be set to 0 if the function is not needed. + Normally, the parse member should be + non-zero or there is little reason for the plugin to exist. + + + + A full-text parser plugin is used in two different contexts, + indexing and searching. In either context, the server calls + the initialization and deinitialization functions at the + beginning and end of processing each SQL statement that causes + the plugin to be invoked. During statement processing, the + main parsing function is called according to its use: + + + + + + + For indexing, the server calls the parser for each column + value to be indexed. + + + + + + For searching, the parser is called to parse the search + string. It might also be called for rows processed by the + statement. In natural language mode, there is no need for + the server to call the parser. For boolean mode phrase + searches or natural language searches with query + expansion, the parser is used to parse column values for + information that is not in the index. Also, if a boolean + mode search is done for a column that has no + FULLTEXT index, the built-in parser + will be called. (Plugins are associated with specific + indexes. If there is no index, no plugin is used.) + + + + + + + Each interface function named in the plugin descriptor should + return 0 for success or 1 for failure, and each of them + receives an argument that points to a + MYSQL_FTPARSER_PARAM structure containing + the parsing context. The structure has this definition: + + + +typedef struct st_mysql_ftparser_param +{ + int (*mysql_parse)(void *param, byte *doc, uint doc_len); + int (*mysql_add_word)(void *param, byte *word, uint word_len, + MYSQL_FTPARSER_BOOLEAN_INFO *boolean_info); + void *ftparser_state; + void *mysql_ftparam; + CHARSET_INFO *cs; + byte *doc; + uint length; + int mode; +} MYSQL_FTPARSER_PARAM; + + + + The structure members are used as follows: + + + + + + + mysql_parse + + + + A pointer to a callback function that invokes the server's + built-in parser. Use this callback when the plugin acts as + a front-end to the built-in parser. When the plugin's + parsing function is called, it processes the input to + extract the text and passes the text to the + mysql_parse callback. + + + + A front-end plugin can extract text and pass it all at + once to the built-in parser, or it can extract and pass + text to the built-in parser a piece at a time. However, in + this case, the built-in parser treats the pieces of text + as though there are implicit word breaks between them. + + + + The first parameter for this callback function is the + mysql_ftparam member of the parsing + context structure. That is, if param + points to the structure, invoke the callback like this: + + + +param->mysql_parse(param->mysql_ftparam, ...); + + + + + + mysql_add_word + + + + A pointer to a callback function that adds a word to a + full-text index or to the list of search terms. Use this + callback when the parser plugin acts as a replacement for + the built-in parser. When the plugin parsing function is + called, it parses the input into words and invokes the + mysql_add_word callback for each word. + + + + The first parameter for this callback function is the + mysql_ftparam member of the parsing context structure. + That is, if param points to the + structure, invoke the callback like this: + + + +param->mysql_add_word(param->mysql_ftparam, ...); + + + + + + ftparser_state + + + + This is a generic pointer. The plugin can set it to point + to information to be used internally for its own purposes. + + + + + + mysql_ftparam + + + + This is set by the server. It is passed as the first + argument to the mysql_parse or + mysql_add_word callback. The plugin + should not modify it. + + + + + + cs + + + + A pointer to information about the character set of the + text, or 0 if no information is available. + + + + + + doc + + + + A pointer to the text to be parsed. + + + + + + length + + + + The length of the text to be parsed, in bytes. + + + + + + mode + + + + The parsing mode. This value will be one of the folowing + constants: + + + + + + + MYSQL_FTPARSER_SIMPLE_MODE + + + + Parse in fast and simple mode, which is used for + indexing and for natural language queries. The parser + should pass to the server only those words that should + be indexed. If the parser uses length limits or a + stopword list to determine which words to ignore, it + should not pass such words to the server. + + + + + + MYSQL_FTPARSER_WITH_STOPWORDS + + + + Parse in stopword mode. This is used for boolean + searches for phrase matching. The parser should pass + all words to the server, even stopwords or words that + are outside any normal length limits. + + + + + + MYSQL_FTPARSER_FULL_BOOLEAN_INFO + + + + Parse in boolean mode. This is used for parsing + boolean query strings. The parser should recognize not + only words but also boolean-mode operators and pass + them to the server as tokens via the + mysql_add_word callback. To tell + the server what kind of token is being passed, the + plugin needs to fill in a + MYSQL_FTPARSER_FULL_BOOLEAN_INFO + structure and pass a pointer to it. + + + + + + + + + + If the parser is called in boolean mode, the + param->mode value will be + MYSQL_FTPARSER_FULL_BOOLEAN_INFO. The + MYSQL_FTPARSER_BOOLEAN_INFO structure that + the parser uses for passing token information to the server + looks like this: + + + +typedef struct st_mysql_ftparser_boolean_info +{ + enum enum_ft_token_type type; + int yesno; + int weight_adjust; + bool wasign; + bool trunc; + /* These are parser state and must be removed. */ + byte prev; + byte *quot; +} MYSQL_FTPARSER_BOOLEAN_INFO; + + + + The parser should fill in the structure members as follows: + + + + + + + type + + + + The token type. This should be one of the following + values: + + + + + + + FT_TOKEN_EOF: End of data + + + + + + FT_TOKEN_WORD: A regular word + + + + + + FT_TOKEN_LEFT_PAREN: The beginning + of a group or subexpression + + + + + + FT_TOKEN_RIGHT_PAREN: The end of a + group or subexpression + + + + + + FT_TOKEN_STOPWORD: A stopword + + + + + + + + + yesno + + + + Whether the word must be present for a match to occur. 0 + means that the word is optional but increases the match + relevance if it is present. Values larger than 0 mean that + the word must be present. Values smaller than 0 mean that + the word must not be present. + + + + + + weight_adjust + + + + A weighting factor that determines how much a match for + the word counts. It can be used to increase or decrease + the word's importance in relevance calculations. + + + + + + wasign + + + + The sign of the weighting factor. + + + + + + trunc + + + + Whether matching should be done as if the + * truncation operator has been given. + + + + + + + Plugins should not use the prev and + quot members of the + MYSQL_FTPARSER_BOOLEAN_INFO structure. + + +
+ +
+ + &title-plugin-creating; + + + Mention the header files. + + + + This section describes a step-by-step procedure for creating a + plugin library that contains a full-text parsing plugin named + simple_parser. This plugin performs parsing + based on simpler rules than those used by the MySQL built-in + full-text parser: Words are non-empty runs of non-empty + whitespace characters. + + + + Each plugin library has the following contents: + + + + + + + A plugin library descriptor that indicates the version + number of the general plugin API that the library uses and + that contains a general declaration for each plugin in the + library. + + + + + + Each plugin general declaration contains information that + is common to all types of plugin: A value that indicates + the plugin type; the plugin name, author, and description; + and pointers to the initialization and deinitialization + functions that the server invokes when it loads and + unloads the plugin. + + + + + + The plugin general declaration also contains a pointer to + a type-specific plugin descriptor. The structure of these + descriptors can vary from one plugin type to another, + because each type of plugin can have its own API. A plugin + descriptor contains a type-specific API version number and + pointers to the functions that are needed to implement + that plugin type. For example, a full-text parser plugin + has initialization and deinitialization functions, and a + main parsing function. The server invokes these functions + when it uses the plugin to parse text. + + + + + + The plugin library contains the interface functions that + are referenced by the library descriptor and by the plugin + descriptors. + + + + + + + To create a plugin library, follow these steps: + + + + + + + Set up the plugin library file descriptor. + + + + Every plugin library includes a library descriptor that + must define two symbols: + + + + + + + _mysql_plugin_interface_version_ + specifies the version number of the general plugin + framework. This is given by the + MYSQL_PLUGIN_INTERFACE_VERSION + symbol, which is defined in the + plugin.h file. + + + + + + _mysql_plugin_declarations_ defines + an array of plugin declarations, terminated by a + declaration with all members set to 0. Each + declaration is an instance of the + st_mysql_plugin structure (also + defined in plugin.h). There must + be one of these for each plugin in the library. + + + + + + + If the server does not find these two symbols in a + library, it does not accept it as a legal plugin library + and rejects it with an error. This prevents use of a + library for plugin purposes unless it was built + specifically as a plugin library. + + + + The standard (and most convenient) way to define the two + required symbols is by using the + mysql_declare_plugin and + mysql_declare_plugin_end macros from + the plugin.h file: + + + +mysql_declare_plugin + ... one or more plugin declarations here ... +mysql_declare_plugin_end; + + + + For example, the library descriptor for a library that + contains a single plugin named + simple_parser looks like this: + + + +mysql_declare_plugin +{ + MYSQL_FTPARSER_PLUGIN, /* type */ + &simple_parser_descriptor, /* descriptor */ + "simple_parser", /* name */ + "MySQL AB", /* author */ + "Simple Full-Text Parser", /* description */ + simple_parser_plugin_init, /* initialization function */ + simple_parser_plugin_deinit /* deinitialization function */ +} +mysql_declare_plugin_end; + + + + For a full-text parser plugin, the type must be + MYSQL_FTPARSER_PLUGIN. This is the + value that identifies the plugin as being legal for use in + a WITH PARSER clause when creating a + FULLTEXT index. (No other plugin type + is legal for this clause.) + + + + The mysql_declare_plugin and + mysql_declare_plugin_end macros are + defined in plugin.h like this: + + + +#define mysql_declare_plugin \ +int _mysql_plugin_interface_version_= MYSQL_PLUGIN_INTERFACE_VERSION; \ +struct st_mysql_plugin _mysql_plugin_declarations_[]= { +#define mysql_declare_plugin_end ,{0,0,0,0,0,0,0}} + + + + When the macros are used as just shown, they expand to the + following code, which defines both of the required symbols + (_mysql_plugin_interface_version_ and + _mysql_plugin_declarations_): + + + +int _mysql_plugin_interface_version_= MYSQL_PLUGIN_INTERFACE_VERSION; +struct st_mysql_plugin _mysql_plugin_declarations_[]= { +{ + MYSQL_FTPARSER_PLUGIN, /* type */ + &simple_parser_descriptor, /* descriptor */ + "simple_parser", /* name */ + "MySQL AB", /* author */ + "Simple Full-Text Parser", /* description */ + simple_parser_plugin_init, /* initialization function */ + simple_parser_plugin_deinit /* deinitialization function */ +} + ,{0,0,0,0,0,0,0} +}; + + + + + + Set up the plugin descriptor. + + + + Each plugin declaration in the library descriptor points + to a type-specific descriptor for the corresponding + plugin. In the simple_parser + declaration, that descriptor is indicated by + &simple_parser_descriptor. The + descriptor specifies the version number for the full-text + plugin interface (as given by + MYSQL_FTPARSER_INTERFACE_VERSION), and + the plugin's parsing, initialization, and deinitialization + functions: + + + +static struct st_mysql_ftparser simple_parser_descriptor= +{ + MYSQL_FTPARSER_INTERFACE_VERSION, /* interface version */ + simple_parser_parse, /* parsing function */ + simple_parser_init, /* parser init function */ + simple_parser_deinit /* parser deinit function */ +}; + + + + + + Set up the functions for each plugin. + + + + The general plugin declaration in the library descriptor + names the initialization and deinitialization functions + that the server should invoke when it loads and unloads + the plugin. For simple_parser, these + functions do nothing but return 0 to indicate that they + succeeded: + + + +static int simple_parser_plugin_init(void) +{ + return(0); +} + +static int simple_parser_plugin_deinit(void) +{ + return(0); +} + + + + Because those functions do not actually do anything, you + could omit them and specify 0 for each of them in the + plugin declaration. + + + + The type-specific plugin descriptor for + simple_parser names the initialization, + deinitialization, and parsing functions that the server + invokes when the plugin is used. The initialization and + deinitialization functions do nothing: + + + +static int simple_parser_init(MYSQL_FTPARSER_PARAM *param) +{ + return(0); +} + +static int simple_parser_deinit(MYSQL_FTPARSER_PARAM *param) +{ + return(0); +} + + + + Here too, because those functions do nothing, you could + omit them and specify 0 for each of them in the plugin + descriptor. + + + + The main parsing function, + simple_parser_parse(), acts as a + replacement for the built-in full-text parser, so it needs + to split text into words and pass each word to the server. + The parsing function's first argument is a pointer to a + structure that contains the parsing context. This + structure has a doc member that points + to the text to be parsed, and a length + member that indicates how long the text is. The simple + parsing done by the plugin considers non-empty runs of + non-empty whitespace characters to be words, so it + identifies words like this: + + + +static int simple_parser_parse(MYSQL_FTPARSER_PARAM *param) +{ + char *end, *start, *docend= param->doc + param->length; + + for (end= start= param->doc;; end++) + { + if (end == docend) + { + if (end > start) + add_word(param, start, end - start); + break; + } + else if (isspace(*end)) + { + if (end > start) + add_word(param, start, end - start); + start= end + 1; + } + } + return(0); +} + + + + As the parser finds each word, it invokes a function + add_word() to pass the word to the + server. add_word() is a helper function + only; it is not part of the plugin interface. The parser + passes the parsing context pointer to + add_word(), as well as a pointer to the + word and its length: + + + +static void add_word(MYSQL_FTPARSER_PARAM *param, char *word, size_t len) +{ + MYSQL_FTPARSER_BOOLEAN_INFO bool_info= + { FT_TOKEN_WORD, 0, 0, 0, 0, ' ', 0 }; + + if (param->mode & MYSQL_FTPARSER_FULL_BOOLEAN_INFO) + param->mysql_add_word(param->mysql_ftparam, word, len, &bool_info); + else + param->mysql_add_word(param->mysql_ftparam, word, len, 0); +} + + + + + + Compile the plugin library as a shared library and install + it in the plugin directory. The procedure for compiling + shared objects vary from system to system. If the library + is named mypluglib, you should end up + with a shared object file that has a name something like + libmypluglib.so. The filename might + have a different extension on your system. + + + + The location of the plugin directory where you should + install the library is given by the + plugin_dir system variable. For + example: + + + +mysql> SHOW VARIABLES LIKE 'plugin_dir'; ++---------------+----------------------------+ +| Variable_name | Value | ++---------------+----------------------------+ +| plugin_dir | /usr/local/mysql/lib/mysql | ++---------------+----------------------------+ + + + + When you install the plugin library, make sure that its + permissions are such that it is executable by the server. + + + + + + Register the plugin with the server. + + + + The INSTALL PLUGIN statement causes the + server to list the plugin in the plugin + table and to load the plugin code from the library file. + Use that statement to register + simple_parser with the server, and then + verify that the plugin is listed in the + plugin table: + + + +mysql> INSTALL PLUGIN simple_parser SONAME 'libmypluglib.so'; +Query OK, 0 rows affected (0.00 sec) + +mysql> SELECT * FROM mysql.plugin; ++---------------+-----------------+ +| name | dl | ++---------------+-----------------+ +| simple_parser | libmypluglib.so | ++---------------+-----------------+ +1 row in set (0.00 sec) + + + + + + Try the plugin. + + + + Create a table that contains a string column and associate + the parser plugin with a FULLTEXT index + on the column: + + + + +mysql> CREATE TABLE t (c VARCHAR(255), + -> FULLTEXT (c) WITH PARSER simple_parser); +Query OK, 0 rows affected (0.01 sec) + + + + Insert some text into the table and try some searches. + These should verify that the parser treats all + non-whitespace characters as word characters: + + + +mysql> INSERT INTO t VALUES + -> ('latin1_general_cs is a case-sensitive collation'), + -> ('I\'d like a case of oranges'), + -> ('this is sensitive information'), + -> ('another row'), + -> ('yet another row'); +Query OK, 5 rows affected (0.02 sec) +Records: 5 Duplicates: 0 Warnings: 0 + +mysql> SELECT c FROM t; ++-------------------------------------------------+ +| c | ++-------------------------------------------------+ +| latin1_general_cs is a case-sensitive collation | +| I'd like a case of oranges | +| this is sensitive information | +| another row | +| yet another row | ++-------------------------------------------------+ +5 rows in set (0.00 sec) + +mysql> SELECT MATCH(c) AGAINST('case') FROM t; ++--------------------------+ +| MATCH(c) AGAINST('case') | ++--------------------------+ +| 0 | +| 1.2968142032623 | +| 0 | +| 0 | +| 0 | ++--------------------------+ +5 rows in set (0.00 sec) + +mysql> SELECT MATCH(c) AGAINST('sensitive') FROM t; ++-------------------------------+ +| MATCH(c) AGAINST('sensitive') | ++-------------------------------+ +| 0 | +| 0 | +| 1.3253291845322 | +| 0 | +| 0 | ++-------------------------------+ +5 rows in set (0.01 sec) + +mysql> SELECT MATCH(c) AGAINST('case-sensitive') FROM t; ++------------------------------------+ +| MATCH(c) AGAINST('case-sensitive') | ++------------------------------------+ +| 1.3109166622162 | +| 0 | +| 0 | +| 0 | +| 0 | ++------------------------------------+ +5 rows in set (0.01 sec) + +mysql> SELECT MATCH(c) AGAINST('I\'d') FROM t; ++--------------------------+ +| MATCH(c) AGAINST('I\'d') | ++--------------------------+ +| 0 | +| 1.2968142032623 | +| 0 | +| 0 | +| 0 | ++--------------------------+ +5 rows in set (0.01 sec) + + + + + + + Note how neither case nor + insensitive match + case-insensitive the way that they would for + the built-in parser. + + +
+ +
+
@@ -937,7 +2364,8 @@ - AGGREGATE CREATE FUNCTION STRING REAL INTEGER DECIMAL RETURNS SONAME + AGGREGATE CREATE FUNCTION STRING REAL INTEGER DECIMAL RETURNS + SONAME Modified: trunk/refman-common/titles.en.ent =================================================================== --- trunk/refman-common/titles.en.ent 2005-12-16 21:02:03 UTC (rev 577) +++ trunk/refman-common/titles.en.ent 2005-12-17 00:07:46 UTC (rev 578) @@ -1332,6 +1332,12 @@ + + + + + +