|
| 1 | +# SQL Developer Examples |
| 2 | +## Worksheet Action |
| 3 | + |
| 4 | +Example extension showing how to add actions to the worksheet context menu and / or toolbar; execute the action directly or in a background task; and present information in a result panel. |
| 5 | + |
| 6 | + |
| 7 | +### Build it |
| 8 | +[Set up your environment](../../setup.md). If using the eclipse project, also modify paths in *SQLDeveloper.userlibraries* and import into eclipse. (This example was built using the "SQLDeveloper 20.1" Library) |
| 9 | +* Build and install using those instructions |
| 10 | + |
| 11 | +### Try it |
| 12 | + |
| 13 | + |
| 14 | +#### First time (Use the trigger to fully load the extension) |
| 15 | +* Open a worksheet |
| 16 | +* Select "Trigger/Load WorksheetAction Extension" from the context menu |
| 17 | +* Close the worksheet |
| 18 | +* Only have to do that the 1st time as extension.xml says to reload once loaded |
| 19 | +* Typically this would be part of a larger extension with natural triggers IMHO & not need this hack. |
| 20 | + |
| 21 | + |
| 22 | + |
| 23 | +#### Then (Extension loaded, now what?) |
| 24 | +* Open a worksheet |
| 25 | +* Positioning |
| 26 | +* * Toolbar: Has entries for BOTH (blue bug) and TOOLBAR_ONLY (yellow bug) |
| 27 | +* * Context menu: Has entries for BOTH (blue bug) and CONTEXT_MENU_ONLY (purple bug) |
| 28 | +* Enabling: |
| 29 | +* * BOTH - Enabled unless the worksheet connection is disconnected |
| 30 | +* * CONTEXT_MENU_ONLY - Always enabled |
| 31 | +* * TOOLBAR_ONLY - Enabled only when there is text in the editor |
| 32 | +* Running (*Open the task progress viewer* (View->Task Progress) *to see the task messages which do not show on the toolbar task viwer.*) |
| 33 | +* * The [ExampleActionTask](src/oracle/db/example/sqldeveloper/extension/worksheetAction/ExampleActionTask.java) sets up a ten second loop to demonstrate setting progress / status as well as checking for cancel/pause |
| 34 | +* * Try pause / resume / cancel |
| 35 | +* * Try running twice without closing result window - note the 2nd one 'replaces' the original. Try pinning the result & running again - a second result window should be used. |
| 36 | +* * try running multiple ones at the same time. You should see them stacked in the task viewer waiting on each other running one at a time. |
| 37 | + |
| 38 | +### Change it |
| 39 | +* Read the section on How it works & play. |
| 40 | +* * How does it work if one of them has a different "connectionName"? (not blocked from running by others with a different name) |
| 41 | +* * How about sending null for callback & id? (no result panel, worksheet not locked when the task runs) |
| 42 | +* * How about adding your own listener to do something? |
| 43 | +* * . . . |
| 44 | + |
| 45 | + |
| 46 | +### How it works |
| 47 | +[extension.xml](etc/extension.xml) |
| 48 | +* In the trigger-hooks/triggers section, declares a dummy trigger action (*WorksheetAction.DUMMY*), with [DummyActionController](src/oracle/db/example/sqldeveloper/extension/worksheetAction/DummyActionController.java) as controller, always enabled on the context menu of any editor to load the extension. |
| 49 | +* In the hooks/jdeveloper-hook section, declares the actions (*WorksheetAction.BOTH*, *WorksheetAction.CONTEXT_MENU_ONLY*, *WorksheetAction.TOOLBAR_ONLY*) we will be adding with this extension. |
| 50 | +* and finally, hooks/sqldev-worksheet-hook declares the [ExampleActionProvider](src/oracle/db/example/sqldeveloper/extension/worksheetAction/ExampleActionProvider.java) that defines the processing for and integrates those actions with the worksheet. |
| 51 | + |
| 52 | +[DummyActionController](src/oracle/db/example/sqldeveloper/extension/worksheetAction/DummyActionController.java) |
| 53 | +* As its name implies, this is a controller that does nothing. It and the associated action exist in this extension only to provide a mechanism to demand load the extension in the absence of any natural trigger(s). |
| 54 | + |
| 55 | +[ExampleActionProvider](src/oracle/db/example/sqldeveloper/extension/worksheetAction/ExampleActionProvider.java) |
| 56 | + This is the brains of the outfit, it |
| 57 | +* Declares contants for the actions ids (matching the ids declared in extension.xml) |
| 58 | +* ```getActionAt``` Creates a worksheet action for each id specifying menu(s), section, and weight for each |
| 59 | +* ```doAction``` Executes the processing for each id with the context passed in. In this case, all three use an [ExampleActionTask](src/oracle/db/example/sqldeveloper/extension/worksheetAction/ExampleActionTask.java) |
| 60 | +* * NOTE: *If the action is quick* (think e.g., format text) *and isn't something that requires a task in its own right* (e.g., anything that talks to the database), you can do / invokeLater the action here and return null. |
| 61 | +* * For tasks, wraps that up for the worksheet along with any listeners and / or viewers desired. For a viewer, we are getting the one from the worksheet context (which is the toolbar task viewer), For listeners, this example adds |
| 62 | +* * * ```getTaskListenerList``` - Log task listener events (INFO/SEVERE for exceptions) controlled by LOG_TASK_EVENTS |
| 63 | +* * * ```getTaskUIListenerList``` - Log task UI listener events (INFO) controlled by LOG_TASK_UI_EVENTS |
| 64 | +* * * (*Uncomment* oracle.level = INFO *in logging.conf to have them show in the log window*) |
| 65 | +* ```checkActionEnabled``` is set up with different criteria for each action |
| 66 | +* * *WorksheetAction.BOTH* - return (we have a connection) |
| 67 | +* * *WorksheetAction.CONTEXT_MENU_ONLY* - return true (always enabled) |
| 68 | +* * *WorksheetAction.TOOLBAR_ONLY* - return (editor has text) |
| 69 | + |
| 70 | +[ExampleActionTask](src/oracle/db/example/sqldeveloper/extension/worksheetAction/ExampleActionTask.java) - a dummy task to show the basic mechanics plus how to attach a result panel to the worksheet. Sets up a ten second loop to demonstrate setting progress / status as well as checking for cancel/pause |
| 71 | +* Why DatabaseQueryTask or derivative? |
| 72 | +* * It serializes executions against a string (connectionName). |
| 73 | +* * If you are going to access the worksheet's (or any shared) connection, you MUST use a task to do so. |
| 74 | +* * This can also be used to serialize executions of your actions. |
| 75 | +* How to set up a result panel |
| 76 | +* How to lock the worksheet while processing |
| 77 | +* How to support pause / cancel |
| 78 | + |
| 79 | +[ExampleResultPanel](src/oracle/db/example/sqldeveloper/extension/worksheetAction/ExampleResultPanel.java)- a really simple result panel just allowing text to be appended. |
| 80 | + |
| 81 | + |
| 82 | + |
0 commit comments