WL#6388: Define and Implement API for Events

Affects: Server-8.0   —   Status: Complete   —   Priority: Medium

Define and Implement API for Events

This worklog specifies interfaces of the following object types:
  - dd::Event
  
This interface should enable,
     - Create new event under given schema.
     - Drop a event.
     - Find event object by name/id.
     - Fetch list of events under given schema.
     - List events under all schema.
  
This WL would introduce new set of DD API's and does not aim to
make server use them yet. A separate WL shall make sql server
changes which would stop using mysql.event MyISAM table and
use mysql.events DD (InnoDB) table.

This worklog mostly follows guidelines from API framework class
definitions (see WL#7284 for more info).

User Documentation
==================

No user-visible changes. No user documentation required.
NF1: No user visible changes.
NOTE: handling of attributes of collection types is described in WL#6380,
section "Common API attribute guidelines".

NOTE: Dictionary_object, Entity_object, Weak_object are specified in
WL#7284.


A) The new Event DD API interface introduced is dd::Event.

The dd::Event interface represents one event under the schema.

Base interfaces:
  - Dictionary_object
  - Entity_object
  - Weak_object

Members:

  * Common attributes:

    - Event name.

    - Event Definer.

    - Time zone.

    - Event Definition.

    - Event Definition in utf8 form.

    - Event Execute at time.

    - Event Interval value.

    - Event Interval field. 

    - Event SQL mode.

    - Event start time.

    - Event end time.

    - Event status

    - Event on completion.

    - Event create time.

    - Event last altered time.

    - Event last executed time.

    - Event originator.

    - Comment

  * References:

    - Strong-reference to dd::Schema object for which this event belongs to.

    - Weak-reference to the client collation which was in effect when the
      event was created.

    - Weak-reference to the connection collation which was in effect when
      the event was created.

    - Weak-reference to the schema collation which was in effect when
      the event was created.

B) Steps to perform various operations on events are,

  1. Steps to add event:
    - Get dd::Schema object for which you want to add event.
    - Invoke dd::Schema::create_event() API.
    - Set dd::Event attributes.
    - Store the dd::Event object. This will store metadata into
      mysql.events.

  2. Find a event by name:
    - Invoke
       bool dd::Dictionary_client::acquire<dd::Event>(
              "schame_name", "event_name", dd::Event** (OUT PARAM));

    The above API would return pointer to dd::Event in last
    parameter with object belonging to 'schema_name.event_name'
    event. Write NULL to last parameter if object is not found.

  3. List events under single schema.
    - Invoke,
      dd::Iterator<const dd::Event> events_iter;
      dd::Dictionary_client::fetch_schema_components(
                               dd::Schema*, &events_iter);

    The above API would return iterator to all events under the
    given schema object.

  4. List events under all schema.
    - Invoke,
      dd::Iterator<const dd::Event> events_iter;
      dd::Dictionary_client::fetch_all_schema_events(&events_iter);

    The above API would return iterator to events under all the
    schema in the database.

  5. Steps to alter event.
    - Follow steps in 2. to get dd::Event object as required.
    - Change required attributes of dd::Event as requested from
      ALTER EVENT.
    - Invoke dd::Dictionary_client::store<dd::Event*>(dd::Event*);

  6. Steps to drop event:
    - Follow steps to get event by name B.2) above.
    - Invoke dd::Dictionary_client::drop<dd::Event*>(dd::Event*);

C) New events DD cache limit is set to zero. Only the events that are
   running would be cached.