Merge pull request #10 from ogobrecht/development

Development

README.md

@@ -5,53 +5,48 @@
     /)__)   focused on easy installation and usage
     -"-"-   combined with nice features.
 
-*This is currently version 1.0-beta8. Feedback and help is welcome.*
+*This is currently version 1.0.0. Feedback and help is welcome.*
 
-**A T T E N T I O N: As long as we are in beta state you should always run the
-uninstallation script (`@uninstall/drop_console_objects.sql`) before you install
-a new version. An existing context does not need to be dropped.**
+A T T E N T I O N: If you have one of the beta versions installed you should
+always run the uninstallation script (`@uninstall/drop_console_objects.sql`)
+before you install a new version. If you created a context, you should also
+delete it: `@drop_context.sql` (you may need higher permissions for this...).
 
 ## Easy to Install
 
-- Works with or without a context.
-- Has a single installation script (can be installed in APEX via "SQL
-  Workshop > SQL Scripts").
+- Works without a context.
+- Has a single installation script (can be installed in APEX via "SQL Workshop >
+  SQL Scripts").
 - If you cannot wait to test it out: Open SQLcl, connect to your desired install
-    schema and call
-    `@https://raw.githubusercontent.com/ogobrecht/console/main/install/create_console_objects.sql`.
-    After some seconds you should be ready to go...
+  schema and call
+  `@https://raw.githubusercontent.com/ogobrecht/console/main/install/create_console_objects.sql`.
+  After some seconds you should be ready to go...
 - Docs: [Installation](docs/installation.md),
   [uninstallation](docs/uninstallation.md).
 
 ## Easy to Use
 
-- Save to run in production without configuration
+- Save to run in production without further configuration
   - Errors are always logged.
   - You can change the default log level for all or specfic sessions from
     `error` to `warning`, `info`, `debug` and `trace`. As a best practice the
     last two should not be set for all sessions on production systems.
   - Specific sessions are identified by the client identifier. If a session has
     no client identifier, console is setting one for you.
-  - You can set specific PL/SQL units (packages, functions, procedures) to a
-    different log level, if you want to monitor for example new code in all
-    sessions (see [console.conf](docs/package-console.md#procedure-conf)).
 - Method names are inspired by the [JavaScript Console
   API](https://developers.google.com/web/tools/chrome-devtools/console/api).
-  Also see the [API overview](docs/api-overview.md) and for more details on the
-  methods including examples the [documentation for the package
-  console](docs/package-console.md).
-- Docs: [Getting started](docs/getting-started.md).
+  Also see the [API overview](docs/api-overview.md).
+- Read more in the [introduction](docs/introduction.md).
 
 ## Nice Features
 
-- Can help you to avoid log spoiling by only logging errors in your outermost
-  package methods without loosing context details with the help of
+- Can help you to avoid cluttered error logs by only logging errors in your
+  outermost package methods without loosing context details with the help of
   [console.error_save_stack](docs/package-console.md#procedure-error_save_stack)
   in the nested methods. This might be the most powerful feature for some
   people...
-- No need to provide manually a scope for your log entries - console
-  does this automatically for you. If needed, you can overwrite the default
-  scope.
+- No need to provide manually a scope for your log entries - console does this
+  automatically for you. If needed, you can overwrite the default scope.
 - Has an optional [APEX error handling
   function](docs/package-console.md#function-apex_error_handling) to log also
   internal errors of the APEX engine.
@@ -72,4 +67,4 @@ a new version. An existing context does not need to be dropped.**
 
 ## Dependencies
 
-Oracle DB >= 12.1
+Oracle DB >= 12.2

apexplugin.json

@@ -1,6 +1,6 @@
 {
   "name": "console",
-  "version": "1.0-beta8",
+  "version": "1.0.0",
   "description": "Oracle Instrumentation Console",
   "keywords": [
     "oracle",
@@ -41,7 +41,7 @@
     }
   },
   "jsFile": {
-    "md5Hash": "0253fa2a20bbaaab96defa6d526786cc",
-    "version": 115
+    "md5Hash": "466d4d1438b06974ca8f8a2362ee9d02",
+    "version": 119
   }
 }

docs/README.md

@@ -3,7 +3,7 @@
 <!-- nav -->
 
 - [Installation](installation.md)
-- [Getting Started](getting-started.md)
+- [Introduction](introduction.md)
 - [API Overview](api-overview.md)
 - [Package Console](package-console.md)
 - [Changelog](changelog.md)

docs/api-overview.md

@@ -2,7 +2,7 @@
 
 [Index](README.md)
 | [Installation](installation.md)
-| [Getting Started](getting-started.md)
+| [Introduction](introduction.md)
 | [API Overview](api-overview.md)
 | [Package Console](package-console.md)
 | [Changelog](changelog.md)
@@ -21,11 +21,10 @@ API](https://developers.google.com/web/tools/chrome-devtools/console/api). This
 means, we have mostly the same log levels and method names. The parameters
 differs a little bit to fit our needs in PL/SQL. Not all methods making sense in
 a PL/SQL instrumentation tool (we have no direct screen) and therefore these six
-are not implemented: dir, dirxml, group, groupCollapsed, groupEnd and countReset
-(instead we have count_end and we ignore the line number, where the count
-occurred). For the two \*_end methods we use snake case instead of camel case
-for readability. As table is a keyword in SQL we named our method table#. The
-log level verbose is splitted into debug and trace.
+are not implemented: clear, dir, dirxml, group, groupCollapsed, groupEnd. We use
+snake case instead of camel case for readability. As table is a keyword in SQL
+we named our method table#. The log level verbose is splitted into debug and
+trace.
 
 We have five log levels:
 
@@ -35,12 +34,7 @@ We have five log levels:
 - Level 4: Debug (instead of verbose in JS console)
 - Level 5: Trace (not existing in JS console)
 
-One pipelined function for viewing the log entries:
-
-- [console.view_last](package-console.md#function-view_last) - for me this is
-  the standard way: `select * from console.view_last(20)` is showing the last 20
-  entries in descending order from the cache AND the log table (if not enough in
-  the cache or cache is disabled)
+Log entries are saved in a table: `select * from console_logs`
 
 The main instrumentation methods:
 
@@ -56,19 +50,26 @@ The main instrumentation methods:
   [log](package-console.md#procedure-log) (level info)
 - [console.debug](package-console.md#procedure-debug) (level debug)
 - [console.trace](package-console.md#procedure-trace) (level trace)
-- [console.count](package-console.md#procedure-count)
-- [console.count_log](package-console.md#procedure-count_log) &
+- [console.count](package-console.md#procedure-count) &
+  [count_reset](package-console.md#procedure-count_reset)
+- [console.count_current](package-console.md#procedure-count_current) &
   [count_end](package-console.md#procedure-count_end) (level info)
-- [console.time](package-console.md#procedure-time)
-- [console.time_log](package-console.md#procedure-time_log) &
-  [console.time_end](package-console.md#procedure-time_end) (level info)
+- [console.count_current](package-console.md#function-count_current) &
+  [count_end](package-console.md#function-count_end) (function overloads, independent of log level)
+- [console.time](package-console.md#procedure-time) &
+  [time_reset](package-console.md#procedure-time_reset)
+- [console.time_current](package-console.md#procedure-time_current) &
+  [time_end](package-console.md#procedure-time_end) (level info)
+- [console.time_current](package-console.md#function-time_current) &
+  [time_end](package-console.md#function-time_end) (function overloads, independent of log level)
 - [console.table#](package-console.md#procedure-table) (level info)
-- [console.assert](package-console.md#procedure-assert)
+- [console.assert](package-console.md#procedure-assert) &
+  [assertf](package-console.md#procedure-assertf)
 - [console.format](package-console.md#function-format)
 - [console.add_param](package-console.md#procedure-add_param)
 
 Additional instrumentation methods:
-
+ 
 - [console.action](package-console.md#procedure-action) &
   [module](package-console.md#procedure-module): Aliases for
   dbms_application_info.set_action and set_module to be friendly to the DBA and
@@ -88,42 +89,40 @@ status of the package console:
 - [console.conf](package-console.md#procedure-conf)
 - [console.init](package-console.md#procedure-init) &
   [exit](package-console.md#procedure-exit) &
-  [exit_stale](package-console.md#procedure-exit_stale)
-- [console.my_client_identifier](package-console.md#function-my_client_identifier)
-  & [my_log_level](package-console.md#function-my_log_level)
-- [console.context_is_available](package-console.md#function-context_is_available)
-  &
-  [context_is_available_yn](package-console.md#function-context_is_available_yn)
-- [console.level_is_warning](package-console.md#function-level_is_warning)
-  &
+  [exit_all](package-console.md#procedure-exit_all)
+- [console.my_client_identifier](package-console.md#function-my_client_identifier) &
+  [my_log_level](package-console.md#function-my_log_level)
+- [console.level_is_warning](package-console.md#function-level_is_warning) &
   [level_is_warning_yn](package-console.md#function-level_is_warning_yn)
 - [console.level_is_info](package-console.md#function-level_is_info) &
   [level_is_info_yn](package-console.md#function-level_is_info_yn)
-- [console.level_is_debug](package-console.md#function-level_is_debug)
-  &
+- [console.level_is_debug](package-console.md#function-level_is_debug) &
   [level_is_debug_yn](package-console.md#function-level_is_debug_yn)
-- [console.level_is_trace](package-console.md#function-level_is_trace)
-  &
+- [console.level_is_trace](package-console.md#function-level_is_trace) &
   [level_is_trace_yn](package-console.md#function-level_is_trace_yn)
 - [console.version](package-console.md#function-version)
-- [console.view_status](package-console.md#function-view_status)
-- [console.view_cache](package-console.md#function-view_cache) &
-  [flush_cache](package-console.md#procedure-flush_cache)
-- [console.clear](package-console.md#procedure-clear)
+- [console.status](package-console.md#function-status)
 
 Additional housekeeping methods:
 
 - [console.purge](package-console.md#procedure-purge) &
   [purge_all](package-console.md#procedure-purge_all)
-- [console.cleanup_job_create](package-console.md#procedure-cleanup_job_create)
-  & [cleanup_job_run](package-console.md#procedure-cleanup_job_run) &
-  [cleanup_job_disable](package-console.md#procedure-cleanup_job_disable) &
-  [cleanup_job_enable](package-console.md#procedure-cleanup_job_enable) &
-  [cleanup_job_drop](package-console.md#procedure-cleanup_job_drop)
+- [console.purge_job_create](package-console.md#procedure-purge_job_create) &
+  [purge_job_run](package-console.md#procedure-purge_job_run) &
+  [purge_job_disable](package-console.md#procedure-purge_job_disable) &
+  [purge_job_enable](package-console.md#procedure-purge_job_enable) &
+  [purge_job_drop](package-console.md#procedure-purge_job_drop)
 
 Additional helper methods (mostly used by console internally) which might also
 helpful for you:
 
+- [console.clob_append](package-console.md#procedure-clob_append) &
+  [clob_flush_cache](package-console.md#procedure-clob_flush_cache)
+- [console.runtime](package-console.md#function-runtime) &
+  [runtime_seconds](package-console.md#function-runtime_seconds) &
+  [runtime_milliseconds](package-console.md#function-runtime_milliseconds)
+- [console.print](package-console.md#procedure-print) &
+  [printf](package-console.md#procedure-printf)
 - [console.split_to_table](package-console.md#function-split_to_table) &
   [split](package-console.md#function-split) &
   [join](package-console.md#function-join)
@@ -134,18 +133,10 @@ helpful for you:
 - [console.to_md_tab_header](package-console.md#function-to_md_tab_header) &
   [to_md_tab_data](package-console.md#function-to_md_tab_data)
 - [console.to_unibar](package-console.md#function-to_unibar)
-- [console.runtime](package-console.md#function-runtime) &
-  [runtime_seconds](package-console.md#function-runtime_seconds) &
-  [runtime_milliseconds](package-console.md#function-runtime_milliseconds)
 - [console.level_name](package-console.md#function-level_name)
 - [console.scope](package-console.md#function-scope) &
-  [calling_unit](package-console.md#function-calling_unit) &
   [call_stack](package-console.md#function-call_stack)
 - [console.apex_env](package-console.md#function-apex_env) &
   [cgi_env](package-console.md#function-cgi_env) &
   [console_env](package-console.md#function-console_env) &
   [user_env](package-console.md#function-user_env)
-- [console.clob_append](package-console.md#procedure-clob_append) &
-  [clob_flush_cache](package-console.md#procedure-clob_flush_cache)
-- [console.print](package-console.md#procedure-print) &
-  [printf](package-console.md#procedure-printf)

docs/build.js

@@ -7,7 +7,7 @@ const renderNavigation = function (type) {
     const entries = [
         {top:true, name:"Index",           file:"README.md"},
         {top:true, name:"Installation",    file:"installation.md"},
-        {top:true, name:"Getting Started", file:"getting-started.md"},
+        {top:true, name:"Introduction",    file:"introduction.md"},
         {top:true, name:"API Overview",    file:"api-overview.md"},
         {top:true, name:"Package Console", file:"package-console.md"},
         {top:true, name:"Changelog",       file:"changelog.md"},

docs/changelog.md

@@ -2,7 +2,7 @@
 
 [Index](README.md)
 | [Installation](installation.md)
-| [Getting Started](getting-started.md)
+| [Introduction](introduction.md)
 | [API Overview](api-overview.md)
 | [Package Console](package-console.md)
 | [Changelog](changelog.md)
@@ -12,14 +12,40 @@
 
 # Changelog
 
+## v1.0.0 (2021-10-04)
+
+- Remove context - we work now with a single record conf table with result cache
+  enabled to simplify the configuration and minify the overhead introduced by
+  console
+  - Rename conf table from `CONSOLE_GLOBAL_CONF` to `CONSOLE_CONF`
+  - Rename purge job from `CONSOLE_CLEANUP` to `CONSOLE_PURGE`
+- Remove the possibility to cache log entries because you can potentially loose
+  log entries - this impacts the possibility to extend the logs with own tables
+  by using the overloaded log functions (which are returning the log ID)
+- Streamline API method names:
+  - Rename `view_client_prefs` to `client_prefs`
+  - Rename `view_status` to `status`
+  - Rename `count_log` & `time_log` to `count_current` & `time_current`
+  - New procedures `count_reset` and `time_reset`
+  - New function overloads for the procedures `count_current` and `time_current`
+- New helper method `assertf` which supports formatted messages (a short form of
+  `console.assert([boolean expression], console.format(...))`)
+- New helper method `exit_all` to exit/unset all client preferences in one go
+- New pipelined function `conf` to show the global configuration as an attribute
+  and value list
+- Change helper functions to_yn, to_string and to_bool to return null on invalid
+  input
+- Minimum database version is now 12.2
+
 ## v1.0-beta8 (2021-08-15)
 
 - More overloads to procedure `add_param`
 - Improved docs
-- ASCII art only on error page
+- ASCII art only on APEX error page
 - Aligned header levels in generated Markdown
 - Change sequence cache for table `console_logs` from default 20 to 1000
-- Fix: Only owner of package `console` is allowed to purge entries and change global config
+- Fix: Only owner of package `console` is allowed to purge entries and change
+  global config
 - Fix: Call stack - include line info only if not null
 - Fix: Function `to_md_code_block` - wrap input in fences only if not null