MDX / JAVA Integration

Java libraries are made available from both MDX expressions and schema data views (aka. ETL).

CLASSPATH: no specific configuration is required to access JAVA classes. All the classes accessible by the icCube server are potentially available. However if you need JAVA classes from JARs that are not available with icCube, simply add them to the icCube-install/lib directory and update accordingly the icCube.bat or icCube.sh files if you're using them (the icCube.exe file is going to use all the JARs available in the lib directory).

Data Views

In the schema builder you can define views as pure Java code. They are similar to Javascript views but are much more faster and should be used instead of Javascript. A JDK (instead of JRE) is required to compile the code in the builder. Note that deployed schema will not compile the code at runtime so a JRE is then enough.

Configuration

The icCube.xml javaViewConfiguration section allows for activating those views. You can as well define standard Java permissions under which the code is going to run. By default, all permissions are off (e.g., cannot access file system). Here is an example of configuration allowing access to the /tmp directory:

        <javaViewConfiguration active="true">

            <permissions>

                <!--
                    An optional list of grants as defined in :

                    https://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.html
                -->
                <grant>java.io.FilePermission "/tmp", "read,write,delete"</grant>

            </permissions>

        </javaViewConfiguration>

MDX Java Native Functions

Accessing Java from MDX can be done via MDX native methods. A JDK (instead of JRE) is required to compile the code in the schema builder. Note that deployed schemas will not compile the code at runtime so a JRE is then enough.

As an example the following is generating a random vector using a ISAAC generator form Apache Math3:

        CREATE NATIVE FUNCTION isaacVector( long seed, int length ) AS
        /* JAVA

            import org.apache.commons.math3.random.ISAACRandom;


            final ISAACRandom generator = new ISAACRandom(seed);

            final double[] values = new double[length];

            for(int ii = 0; ii < length; ii++)
            {
                values[ii ] = generator.nextInt();
            };

            return values;

        */

The following parameter types are available:

        JAVA types:

            double  ( Double  )
            float   ( Float   )
            long    ( Long    )
            int     ( Integer )
            boolean ( Boolean )

            String


        JODA Date/Time

            LocalDate
            LocalDateTime


        IOlapScalar

            /**
             * Null scalar/value: IOlapScalar methods typically return an empty value instead of JAVA null.
             */
            boolean isEmpty();


        IOlapNumeric extends IOlapScalar

            boolean isDecimal();
            boolean isDouble();

            double  value();

            double  doubleValue();
            float   floatValue();
            long    longValue();
            int     intValue();


        IOlapDoubleVector extends IOlapScalar

            int           size();
            double        get(int index);

            + all available methods defined in Vector( MDX++ ).


        IOlapComparableList extends IOlapScalar

            int           size();
            Comparable    get(int index);

            String        getAsDate(int index);
            LocalDate     getAsDate(int index);
            LocalDateTime getAsDateTime(int index);

NULL/Empty parameters and return values

Passing an MDX null entity to a parameter whose type is primitive will generate an error. This might happen when you evaluate an MDX tuple and the result is empty. To handle properly those scenarios you can use an object, for example Double instead of double as parameter type; in that case a null JAVA is being sent.

If you want to return a null/empty, simply return a JAVA null.

Configuration

The icCube.xml javaMdxNativeConfiguration section allows for activating those views. You can as well define standard Java permissions under which the code is going to run. By default, all permissions are off (e.g., cannot access file system).

J! Accessor

Accessing Java methods using the notation J!Package.Class.Method( ...) has been deprecated. You should instead use native functions as described before.

J! Configuration

By default JAVA support is turned off. It can be activated via the _ javaMdxConfiguration _ section in the file icCube.xml. Once activated, the allowedPackage, allowedClass and allowedMethod defines the JAVA packages and classes that can be accessed via MDX.

J! Security

Note that when exposing icCube to a wide/public audience we strongly advise either to keep JAVA support turned off and instead setup a thin wrapper library that is exposing explicitly JAVA methods as MDX functions (contact us for more information) or check carefully the allowed packages and classes.

J! Usage

The notation J!Package.Class.Method( ...) allows for accessing any JAVA static method or field from an MDX statement. Note that the conversion of the parameters (as well as the result) is handled automatically by the MDX engine. The following calculated member is computing the square root of PI using JAVA classes:

WITH MEMBER [Measures].[val] AS J!Math.sqrt( J!Math.PI )

As seen in the previous example, the fully qualified class name is not required. However, in case of ambiguities (i.e., the class is available in more than one package) then a part or the whole package can be specified:

J!java.Math.PI or J!java.lang.Math.PI

J! CLASSPATH

No specific configuration is required to access JAVA classes. All the classes accessible by the icCube server are potentially available. However if you need JAVA classes from JAR that are not available with icCube, simply add them to the icCube-install/lib directory and update accordingly the icCube.bat or icCube.sh files if you're using them (the icCube.exe file is going to use all the JARs available in the lib directory).

J! Class Repository

In order to be able to use the class names without having to specify the whole package names a repository of all the available classes is possibly built. This repository can be configured within the file $install/bin/icCube.xml using classRepositoryActive and classRepositoryPath).

Documentation