Enabling the Studio Customization Toolkit Client

This topic describes how to enable the Studio Customization Toolkit to generate a stack trace that is passed as a parameter whenever the client makes a call into the 3DSpace kernel.

This task shows you how to:

See Also
About the Studio Customization Toolkit Origin Trace Facility
Example of Studio Customization Toolkit Origin Trace Ouput

Enable Tracing in the XML Applet

To enable the Web version of 3DSpace to generate a stack trace for all calls:

  1. Uncomment the following line in the JSP that is used to start the MAtrix Web Navigator: 

    props.put("ADKTrace", "TRUE");

    The default setting is "FALSE".

  2. Enable the platform and web servers to print the stack traces in a log file.

Enable Tracing in Custom Studio Customization Toolkit Applications

To enable this level of tracing in the Studio Customization Toolkit client application:

  1. Use one of the following methods in the matrix.db.Context class:
    • public static void setOriginTraceAll(boolean set)
    • public static boolean getOriginTraceAll()
  2. For tracing on a single Context object, JSP, or JPO, use:
    • public void setOriginTrace(boolean set)
    • public boolean getOriginTrace()
  3. Enable the platform and web servers to print the stack traces in a log file.

Enable the Web/Application Server

To trace all servlets and JSPs executed on the server:

Uncomment the following line in your framework.properties file:

ematrix.origin.trace=true

This enables tracing globally for all context objects created.

Note: Alternatively, you can add this setting to a web.xml.part file (either by modifying the file in a blown-out WAR file or by using the application server's administration console to modify an already deployed web application).

When tracing JSPs, it is helpful to configure the web servers to "keep generated" Java code for JSPs. Consult your web server documentation for instructions.

Enable the Live Collaboration Kernel

To enable the 3DSpace Service or Studio Modeling Native Apps to print the stack traces into a file called matrixserver.log:

  1. Add the following line to the .ini file or the emxEnv.sh script:

    MX_VERBOSE_TRACE=matrixserver.log

  2. Also include the appropriate settings to indicate which Studio Customization Toolkit calls to trace:
    • To trace all Studio Customization Toolkit calls, use:
      MX_ADK_TRACEALL=true
    • To trace specific Studio Customization Toolkit calls, enable each JDL call individually using its name as the keyword. Do not include MX_ADK_TRACEALL. For example:
      executeCmd_bosMQLCommand=true
evaluate_bosQuery=true
start_bosContext=true

    On Windows:
    A file named adkTrace.ini is installed in the ENOVIA_INSTALL directory when the Studio Modeling Native Apps or the 3DSpace Service is installed. This file contains samples of all possible per-Studio Customization Toolkit-call trace settings. Administrators can use this file to copy settings to their enovia.ini files for the Studio Modeling Native Apps or 3DSpace Service (previously matrix.ini or ematrix.ini, respectively) when they want to enable tracing on a particular Studio Customization Toolkit call.
    On Linux:
    A file called adkTrace.sh is installed in the SERVERHOME directory when the Studio Modeling Native Apps or the 3DSpace Service is installed. Both the Studio Modeling Native Apps and the 3DSpace Service’s shell scripts call this auxiliary shell script, which contains commented-out/disabled samples of all possible per-ADK call trace settings (as well as the traceall setting). Administrators can uncomment those that they wish to have traced.

Understand Studio Customization Toolkit Exceptions

The freeContext.bosInterface call does not include a stack trace; it is called by the Java garbage collector.

The allocExternalContext.bosInterface stack trace is supplied as a parameter to the call in verbose logging if Studio Customization Toolkit origin tracing is enabled on the client side (regardless of the MX_ADK_TRACEALL setting). If client side tracing is disabled, a blank stack trace is generated. To prevent unwanted network traffic:

Ensure that the stack trace for allocExternalContext.bosInterface is blank, thus ensuring that the feature is disabled on the client side (JPO, applet, or web server).