As with other schema object identifiers, the name is case-sensitive if enclosed in double quotation marks. If the enclosing quotation marks are omitted, the name is implicitly converted to uppercase.

MLE environments cannot contain import mappings that conflict with the names of the MLE built-in modules (mle-js-oracledb, mle-js-bindings, mle-js-plsqltypes, mle-js-fetch, mle-encode-base64, mle-js-encodings, and mle-js-plsql-ffi). If you attempt to add such a mapping using either the CREATE MLE ENV or ALTER MLE ENV DDL, the operation fails with an error.

In its most basic form, an environment can be created empty as shown in the following snippet:

CREATE MLE ENV myEnv;

Subsequent calls to ALTER MLE ENV can be used to add properties to the environment.

Just like with MLE modules, it is possible to append the OR REPLACE clause to instruct the database to replace an existing MLE environment rather than throwing an error.

Furthermore, the IF NOT EXISTS clause can be used instead of the OR REPLACE clause to prevent the creation of a new MLE environment in the case that one already exists with the same name. In this case, the statement used to create the environment changes to the following:

CREATE MLE ENV IF NOT EXISTS myEnv;

You can optionally include the PURE keyword to indicate that any JavaScript code using the environment should be run in a restricted execution context that disallows access to the database state. PURE execution provides an extra layer of security by isolating certain code, such as third-party JavaScript libraries, from the database. Environments that are created using the PURE keyword can be referenced by MLE modules and when using DBMS_MLE for dynamic execution. The PURE keyword can be specified as follows:

CREATE OR REPLACE MLE ENV my_pure_env PURE;

The new environment inherits all settings from its source. Subsequent changes to the source are not propagated to the clone. A clone can be created as shown in the following statement:

CREATE MLE ENV MyEnvDuplicate CLONE MyEnv

The separation of code allows for finer control over changes and the ability to write more reusable code. Simplified code maintenance is another positive effect of this approach.

Only those identifiers marked with the export keyword are eligible for importing.

Modules attempting to import functionality from other modules stored in the database require MLE environments in order to perform name resolution. To create an MLE environment with that information, the IMPORTS clause must be used. Example 3-13 demonstrates how a mapping is created between the identifier po_module and JavaScript module PO_MODULE, created in Example 3-1.

Multiple imports can be provided as a comma-separated list. In Example 3-13, the first parameter in single quotation marks is known as the import name. The import name is used by another module's import statement. In this case, 'po_module' is the import name and refers to the module of the same name.

The CREATE MLE ENV command fails if a module referenced in the IMPORTS clause does not exist or is not accessible to you.

Built-in JavaScript modules can be imported directly without having to specify additional MLE environments.

CREATE OR REPLACE MLE ENV 
    po_env
IMPORTS (
    'po_module' MODULE PO_MODULE
);

CREATE OR REPLACE MLE MODULE import_example_module
LANGUAGE JAVASCRIPT AS
 
import * as po from "po_module";
/**
* use po_module's getValue() function to calculate the value of
* a purchase order. In later chapters, when discussing the MLE
* JavaScript SQL driver the hard-coded value used as the PO will
* be replaced by calls to the database
* @returns {number} the value of all line items in the purchase order
*/
export function purchaseOrderValue() {
 
    const purchaseOrder = {
        "PONumber": 1600,
        "Reference": "ABULL-20140421",
        "Requestor": "Alexis Bull",
        "User": "ABULL",
        "CostCenter": "A50",
        "ShippingInstructions": {
            "name": "Alexis Bull",
            "Address": {
                "street": "200 Sporting Green",
                "city": "South San Francisco",
                "state": "CA",
                "zipCode": 99236,
                "country": "United States of America"
            },
            "Phone": [
                {
                    "type": "Office",
                    "number": "909-555-7307"
                },
                {
                    "type": "Mobile",
                    "number": "415-555-1234"
                }
            ]
        },
        "Special Instructions": null,
        "AllowPartialShipment": true,
        "LineItems": [
            {
                "ItemNumber": 1,
                "Part": {
                    "Description": "One Magic Christmas",
                    "UnitPrice": 19.95,
                    "UPCCode": 13131092899
                },
                "Quantity": 9.0
            },
            {
                "ItemNumber": 2,
                "Part": {
                    "Description": "Lethal Weapon",
                    "UnitPrice": 19.95,
                    "UPCCode": 85391628927
                },
                "Quantity": 5.0
            }
        ]
    };
 
    return po.orderValue(purchaseOrder.LineItems);
}
/

CREATE FUNCTION purchase_order_value
RETURN NUMBER AS
MLE MODULE import_example_module
ENV po_env
SIGNATURE 'purchaseOrderValue';
/

SELECT purchase_order_value;
/

PURCHASE_ORDER_VALUE
--------------------
               279.3

Any options specified in the MLE environment take precedence over the default settings.

Multiple language options can be provided as a comma-separated list of '<key>=<value>' strings. The following snippet demonstrates how to enforce JavaScript's strict mode.

CREATE MLE ENV MyEnvOpt
    LANGUAGE OPTIONS 'js.strict=true';

Changes made to the language options of an environment are not propagated to execution contexts that have already been created using the environment. For changes to take effect for existing contexts, the contexts need to be dropped and recreated.

Topics

Use the ALTER MLE ENV clause to modify language options, as shown in the following snippet:

ALTER MLE ENV MyEnvOpt
    SET LANGUAGE OPTIONS 'js.strict=false';

Imports not specified during an environment's creation can be added to existing MLE environments using the ADD IMPORTS clause. Import names, once defined, are static and must be dropped before they can be added as desired. Assuming you have run a new CREATE MLE DDL to replace IMPORT_EXAMPLE_MODULE from Example 3-1 with the module name IMPORT_EXAMPLE_MODULE_V2, the following statement will run successfully:

ALTER MLE ENV po_env 
ADD IMPORTS (
    'import_example' MODULE IMPORT_EXAMPLE_MODULE_V2
);

Any imports no longer needed can be dropped using the DROP IMPORTS clause:

ALTER MLE ENV po_env DROP IMPORTS('import_example');

The case of the import identifier must match that in the data dictionary's USER_MLE_ENV_IMPORTS view.

For more information about *_MLE_ENVS, see Oracle Database Reference.

SELECT ENV_NAME, LANGUAGE_OPTIONS
FROM USER_MLE_ENVS
WHERE ENV_NAME='MYENVOPT'
/

ENV_OWNER            ENV_NAME   LANGUAGE_OPTIONS
-------------------- ---------- ----------------------
JSDEV01              MYENVOPT   js.strict=true

MLE environments are the key enablers for resolving names of imported modules. Example 3-16 demonstrates a query against USER_MLE_ENV_IMPORTS to list IMPORT_NAME, MODULE_OWNER, and MODULE_NAME.

For more information about *_MLE_ENV_IMPORTS, see Oracle Database Reference

SELECT IMPORT_NAME, MODULE_OWNER, MODULE_NAME
    FROM USER_MLE_ENV_IMPORTS
    WHERE ENV_NAME='MYFACTORIALENV';
/

IMPORT_NAME            MODULE_OWNER              MODULE_NAME
---------------------- ------------------------- ------------------
FACTORIAL_MOD          DEVELOPER1                FACTORIAL_MOD