[ https://forge.continuent.org/jira/browse/SEQUOIA-963?page=comments#action_14127 ]
Robert Hodges commented on SEQUOIA-963: --------------------------------------- Here is the documentation for this feature. This needs to be folded into SEQUOIA documentation at some point in the near future. 1 Overview Interceptors are a new feature in Sequoia that permit you to add extra code at specific locations in the flow of processing. Interceptors allow you to add call-outs that are dynamically loaded when the controller starts up. Interceptors come in two flavors: 1.) Front-end interceptors are invoked in the DatabaseWorkerThread after the request has been parsed but before it is submitted to group communications. This allows you to do up-front processing easily, though there are some limitations to changes you may make. 2.) Back-end interceptors are invoked shortly before SQL execution. You can use these interceptors to perform more extensive SQL transformations. Interceptors add a number of new interfaces. These are fully documented in Javadoc, but here is a short synopsis of their uses. All interfaces are in package org.continuent.sequoia.controller.interceptors InterceptorConfigurator - Instantiates and sets interceptor properties. RequestFacade - An interface to the SQL request that exposes properties in a generic way. RequestIntercaptor - Interface implemented by all interceptors. SessionFacade - An interface that supplies information related to the Sequoia client session 3 Configuring Interceptors Interceptor are loaded in when the controller starts up. The controller looks for the following properties in the controller_default.properties file: # List of backend intercepter classes separated by semi-colons. These # interceptors examine and/or alter SQL requests before they are submitted # against a specific backend. Interceptors run in the order in which # they are listed. backend.interceptors= # List of frontend intercepter classes separated by semi-colons. These # interceptors examine and/or alter SQL requests during initial processing # in the virtual database worker thread. Interceptors run in the order in # which they are listed. frontend.interceptors= To add an interceptor, just add the fully qualified interceptor class name to the correct property, depending on when you want the interceptor to run. Here's an example: backend.interceptor=org.foo.interceptors.MyInterceptorImplementation Interceptors remain loaded for the duration of controller execution. 4 Caveats Interceptors are useful but can create some new types of errors. Here are caveats to follow: a.) Initialization failures. The controller loads interceptors at start-up time. If an interceptor cannot be loaded into the JVM, for example due to a class path problem, the controller will signal a fatal error and exit. b.) Front-end interceptor limitations. In general, it is unwise to make any SQL changes in front-end interceptors. Front-end interceptors may not change SQL in a way that would cause it to parse to another type of SQL statement later on. For example, if you try to change an UPDATE statement to a DELETE, it will cause an internal failure. This is because Sequoia parses SQL statements on both controllers when the statement is distributed across controllers. c.) Back-end interceptors. When writing back-end interceptors, you should be aware that they are called once per request for *each* enabled backend. If you make SQL changes in a back-end interceptor, you should add logic to ensure that the change is not made more than once if the interceptor is called multiple times for the same request. 5 Tests Unit tests are provided in package org.contiuent.sequoia.controller.interceptors.test. Use the unit tests to see basic examples of use. Run the tests to check any changes to this feature. > Add RequestInterceptor feature to allow easy addition of logic to monitor and > transform requests > ------------------------------------------------------------------------------------------------ > > Key: SEQUOIA-963 > URL: https://forge.continuent.org/jira/browse/SEQUOIA-963 > Project: Sequoia > Type: New Feature > Components: Core > Versions: Sequoia 2.9 > Environment: All > Reporter: Robert Hodges > Assignee: Robert Hodges > Priority: Critical > Fix For: Sequoia 2.9 > > Original Estimate: 1 week > Remaining: 1 week > > It is a common requirement to want to add additional logic that can piggyback > on top of requests in order to monitor or transform them. Here are some > examples: > 1.) Checking for SQL that is forbidden by a particular application. > 2.) Performing transformation on SQL such as adding comments to make it > easier to implement replication strategies between clusters. > 3.) Logging interesting information about requests. > To enable these types of applications I plan to add a new feature called a > RequestInterceptor, which is a specialized interface that is invoked within > VirtualDatabaseWorker threads immediate prior to submitting SQL to the VDB > for execution. The RequestInterceptor is invoked and will receive the > Request as well as some additional information like the VDB object. The > RequestInterceptor can examine the request, make well-defined changes, and > perform functions like logging or monitoring as desired. > The implementation will be approximately as follows. > 1.) The RequestInterceptor interface will have a method that is invoke for > each request. Implementations can perform arbitrary processing in this > method. Multiple RequestInterceptors can be added in which case the > processing methods are invoked in succession. > 2.) Request data will be passed in using interfaces that wrap the underlying > AbstractRequest object. The interfaces will expose only a limited amount of > information and prevent unfortunate transformations that might cause further > processing to fail. There may be additional information passed in such as > the VDB and an abstraction of information in the VirtualDatabaseWorkerThread > (i.e., the closest thing we have to a session). > 3.) There will be a mechanism to configure zero or more RequestInterceptors > for each controller and define parameters for each RequestInterceptor > implementation. This may require an additional configuration file. > 4.) There will be a well-defined lifecycle for RequestInterceptor instances > in which they are initialized with configuration data, invoked zero or more > times, and shut down at controller termination. > 5.) The data structures associated with the RequestInterceptor will be > largely free of dependencies on other Sequoia packages and will be easy to > unit test outside the controller. > This mechanism will apply to request on the way in to the VDB only. Later on > it may make sense to enlarge the feature to permit RequestInterceptors to > generate errors or their own result sets. > Comments and suggestions are welcome. I hope this will turn out to be a > useful feature for Sequoia users. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: https://forge.continuent.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira _______________________________________________ Sequoia mailing list [email protected] https://forge.continuent.org/mailman/listinfo/sequoia
