Executing Your Own Classes from a Library

The library allows you to store your RedwoodScript code for use in Redwood Server, in one or multiple triggers, for example, or in Redwood Expression Language.

You can write your own code directly in your library or add jar files to your library. RedwoodScript code in a library must always be in Full mode, that is start with package com.redwood.scheduler.custom.... This code can then be accessed from triggers, actions, Process Definitions, period functions, and Redwood Expression Language.

Note: Customer library names must always start with Custom_ or you will not be able to save the library.

Note: When you modify a library, all objects that use the library will have to be recompiled. This can be time-consuming; to reduce the impact, you can set the library of Process Definitions, actions and triggers that do not use the Custom library to use None library.

Custom Library and Customer Libraries

Actions, triggers, period functions and Process Definitions (RedwoodScript contexts) depend on the Custom library. You may specify your own library in which case the object will depend on your library and the Custom library.

If you do not want to depend on a library, you can use the None library - this will also prevent superfluous recompiles when the Custom library changes.

It is recommended to spread your code functionally across multiple libraries if you have a lot of RedwoodScript objects that use libraries. When you modify a library, all RedwoodScript contexts, as well as any other RedwoodScript objects that use the library will be recompiled when the library changes. When you specify a library on a RedwoodScript context, the context will depend on the Custom library as well as the library you specified (except for the special None library); you cannot specify more than one library on a context.

Shared code should go into the Custom library, function-specific code should go into individual libraries to balance recompile times.

Using Loggers in Libraries

A logger is an object that allows you to write log messages. Loggers have a category and a level. The category is the source of the message, and is arranged hierarchically. All loggers related to Redwood Server are in the category com.redwood., under which there are many more sub-categories (and sub-sub-categories and so on). Loggers also have a level, this controls the amount of information that is logged from a particular source. The levels (in order of most to least important) are:

• FATAL - messages that will cause an immediate issue for the system or important customer functionality, that require human intervention to resolve.
• ERROR - errors that only effect part of the system (for example a process failing or a file not being present)
• WARN - potential errors or bad configuration.
• INFO - informational messages, generally about progress in a long running task.
• DEBUG - detailed information about system progress.

You use the default loggers that are available in the context of the library; if you want to create your own, you should create one for each class that requires a separate logger.

package ...;

import com.redwood.scheduler.infrastructure.logging.api.Logger;
import com.redwood.scheduler.api.scripting.variables.LibraryLoggerFactory;

public class MyClass
{
  private static final Logger log = LibraryLoggerFactory.getLogger(MyClass.class);

  ...

  log.info("Reached important point");

  ...
}

The logger object has two methods for each level, one that takes a message, and another that takes a message and a Throwable object (an exception).

  Logger log = ...;

  log.debug("Some information useful to developers is " + someVariableName);

  log.info("Finished Pass 2/3");

  try
  {
    ...
  }
  catch (IOException ioe)
  {
    log.error("Error accessing file", ioe);
    throw ioe;
  }

Accessing Libraries in RedwoodScript

To use your methods from within RedwoodScript, you first need to set the library containing your code on the object, you can then use your code using one of the following:

• specifying <package_name>.<class_name>.<method_name>
• import your class using the following import statement import <package_name>.<class_name>; and use <class_name>.<method_name>

Note: You should not use the jcs prefix in the names of your methods, as this prefix is reserved for the system.

Accessing Libraries in Redwood Expression Language

You can use your methods in Redwood Expression Language throughout the product by specifying REL Entry Points with the following information:

• Name - the name of the method to be used in Redwood Expression Language
• FQ Class Name - the fully qualified class name
• Method Signature - the method syntax

Note: You should not mix code in a same class that is to be used in Redwood Expression Language and RedwoodScript. See Mixing REL and RS Code in a Library for more information.

Note: You should not use the jcs prefix in the names of your methods, as this prefix is reserved for the system.

Persisting Sessions in Libraries

It is not recommended to persist a session in your library code that you intend to use in Redwood Expression Language, as it can have side-effects. The behavior or side-effects might even change from one release to the next without prior notice.

Persisting a session in your library code used for RedwoodScript may have side effects as well, especially when the code is used in triggers, process actions, or Import Rule Set actions. It is strongly recommended not to persist a session in your library code if it is used in triggers, process actions, or Import Rule Set actions.

You may persist a session in your library code when it is used by alert escalations, alert sources, or email alert gateways and none of the previously mentioned objects.

Sessions in Libraries and Restarted Processes

When you called ScriptSessionFactory.getSession() within a library from REL, the call would return null for restarted processes. This has been fixed, however, the session is read-only, for default expressions and in-expressions of parameter mappings.

Context Menu

Libraries support the following context menu options.

Note: For generally applicable object context menu options, see Object Context Menu.

Finding Libraries

You can search for libraries using filters and the Search Libraries box on the Libraries tab. This box is known as the IntelliSearch box and located under your username on the top right-hand side of the user interface. Filters allow you to specify a list of objects with static criteria. IntelliSearch allows you to specify complex queries in a simple way using prefixes. Prefixes are used to specify which property you are searching in and have short as well as long syntaxes. For example, if you want to display all libraries with the term trigger in the comment, you would use the search criteria as follows:

c:trigger

You can search more than one property, as follows:

c:trigger n:JV

Note: No spaces should be entered before or after the colon ( : ).

See the Advanced Object Search for more information.

The following table illustrates the available prefixes for libraries:

Deleting Libraries

You can only delete libraries when no other objects relate to them. For example, if there are Process Definitions that use the library, the library cannot be deleted until all Process Definitions that use it have been modified. You can see all Process Definitions that relate to the library in Related Objects in the lower detail pane and on the show page.

The table in related objects contains three columns:

• Type - the type of object with a link to it
• Related Object - the name of the object with a link to it
• Used As - objects can sometimes be used in different roles

Security

The privileges available in the Security tab are as follows.

For more information, see Security Tab.

Procedure

Create you own package in the custom library

1. Navigate to "Scripting > Libraries".
2. Choose Edit from the context menu of the library.
3. Choose the Source tab, choose New Library and enter your code.
4. Choose Save to save your newly added package.
5. Choose the REL Entry Points tab and fill in the following information:
6. Name - the desired name of the method, the name should remind others of what the method does.
7. FQ Class Name - the fully qualified name of the class, <package_name>.<class_name>.
8. Method Signature - the signature of the method, for example, its name in your code and the types of arguments that should be provided.

Add a jar file to the library

1. Navigate to "Scripting > Libraries".
2. Choose Add Jar from the context menu of the library.
3. In the Import Jar File Into Library make sure the Library Name is correct and navigate to the jar file. The jar file needs to be accessible to the system where Redwood Server is running.
4. Choose Send and wait until the jar file has been loaded. The System_Import_JarFile process gets submitted automatically to upload the jar file, if this process fails, the jar file has not been added. Please monitor the process and inspect the stderr.log and stdout.log files for more information.

See Also

• Library Example

libraries