Configuring Access to Custom Functions

Custom functions are user-defined functions that performed specialized tasks. Before a BEA Liquid Data for WebLogic^TM query can access a custom function, the custom function must be configured on the Custom Functions tab on the Liquid Data node in the Administration Console. This topic describes how to configure access to custom functions. It includes the following topics:

• About Custom Functions
• Administration Tasks for Custom Functions
• Creating a Custom Function Description
• Summary of Configured Custom Function Groups
• Configuring Secure Access to Custom Function Descriptions
• Modifying a Custom Function Description
• Removing a Custom Function Description

For additional information, see Using Custom Functions in Invoking Queries Programmatically.

 

---

About Custom Functions

The Data View Builder provides a set of standard functions for use in creating data views and queries using various types of joins and mappings. You can also extend the Data View Builder by creating custom functions to perform specialized tasks.

This topic includes the following sections:

• Use Cases for Custom Functions
• Components of Custom Functions

Use Cases for Custom Functions

Custom functions allow you to perform specialized operations that are not available in standard functions. There are many possible use cases for custom functions in Liquid Data. The following list provides just a few examples of what custom functions can do:

• Process a column in a database that contains data requiring specialized interpretation. For example, a name_title column might contain numeric codes (1, 2, 3, and so on) that represent text (Mr., Mrs., Ms., Dr., and so on) rather than the text itself. A  custom function could be created to decode the data in the column and return the text instead.
• Calculate a special mathematical formula, equation, or operation.
• Invoke stored procedures on a JDBC data source via the query EJB.

Components of Custom Functions

A custom function is implemented in Java code and declared in a custom functions library definition (CFLD) file. For detailed information about these tasks, see Using Custom Functions in Invoking Queries Programmatically.

Once implemented and declared in the Liquid Data Server repository, a custom function description must be created for each custom function. A custom function description defines the following information:

• logical name of the custom function as declared in the CFLD file
• name of the CFLD file in which the custom function is declared

Once configured according to the instructions in this topic, custom functions with custom function descriptions will show up as functions available for use in any Data View Builder client that connects to this server.

 

---

Administration Tasks for Custom Functions

To configure custom functions, administrators perform the following tasks:

1. Add the JAR file containing the custom function implementation to the custom_lib folder in the Liquid Data Server repository, as described in Uploading Files to the Server Repository.

2. Add the path to the JAR file in the Custom Functions Classpath field on the General tab on the Liquid Data node, as described in Configuring Liquid Data Server Settings.

3. Add the CFLD file containing the custom function declaration to the custom_functions folder in the Liquid Data Server repository, as described in Uploading Files to the Server Repository.

4. For each custom function, create a custom function description, as described in Creating a Custom Function Description.

5. If security is enabled, assign ACLs to the custom function description, as described in Configuring Secure Access to Custom Function Descriptions, and also assigning ACLs to the JAR and CFLD files in the Liquid Data Server repository, as described in Configuring Secure Access to Items in the Server Repository.

 

---

Creating a Custom Function Description

Note: You must log in with modify access before you can create a custom function description. For more information, see Administration Console Security.

To create a custom function description for a group of custom functions:

1. Make sure that the JAR file containing custom function implementations resides in the custom_lib folder in the Liquid Data Server repository, and that the CFLD file declaring the custom functions resides in the custom_functions folder in the Liquid Data Server repository.

2. In the left pane, click the Liquid Data node.

3. In the right pane, click the Configuration tab.

4. Click the Custom Functions tab.

5. Click the Configure a new Custom Function description text link.

   The Administration Console displays the configuration tab for creating a new custom function description.

6. Enter the information described in the following table:

   Table 13-1 Custom Function Description Information  

   Field	Description
   Name	Logical name of the group of custom functions declared in the custom functions library definition (CFLD) file. Custom function names must start with an alphabetic character (a-z or A-Z).
   Value	File name of the CFLD file that declares this custom function in an XML format. This file usually resides in the custom_functions folder in the Liquid Data Server repository, which is described in Server Repository File System Hierarchy. Either type the CFLD file name or click Browse Repository to browse the custom_functions folder and select it.

   
    

7. Click Create.

   The Administration Console displays the new custom function description in the summary table.

 

---

Summary of Configured Custom Function Groups

The summary table on the Custom Functions tab on the Liquid Data node shows a list of custom function groups that have been configured with custom function descriptions on the current server. From the summary list, you can perform the following tasks:

• Navigate to the custom function description for a particular custom function group by clicking on it in the table.
• Configure security on a custom function group by selecting the group name and clicking the Configure ACL link. The Configure ACL link takes you to the Compatibility Security ACL configuration tabs. For more information, see Configuring Secure Access to Custom Function Descriptions.
• Remove an existing custom function group from the Liquid Data function library by clicking the trash can at the far right of the selected function.

 

---

Configuring Secure Access to Custom Function Descriptions

Note: You must log in with modify access before you can assign ACLs to a custom function description. For more information, see Administration Console Security.

If security is enabled on the Liquid Data server, you need to configure security for each custom function description using Access Control Lists (ACLs). You need to assign execute permissions to users who are authorized to execute queries that use particular custom functions. Before you assign ACLs, you must define groups, users, and access levels. For more information about Liquid Data security, see Implementing Security.

Note: In the Repository tab on the Liquid Data node, you can assign modify and read access to CFLD files and JAR files associated with custom functions. The ACLs assigned in the Custom Functions tab determine whether a user can execute a query in which a custom function is used. The ACLs in the Repository tab determine whether the user logged into the Administration Console can modify or read the CFLD or JAR files in the repository.

 

To assign ACLs to a custom function description:

1. In the left pane, click the Liquid Data node.

2. In the right pane, click the Configuration tab.

3. Click the Custom Functions tab.

4. Select (check) the check box next to the custom function description to which you want to assign ACLs.

5. Click Configure ACL.

6. The Administration Console displays the WebLogic Server ACL configuration page.

7. To add a new ACL, click on Add a new Permission.

8. The Administration Console displays the Group tab.

9. Assign execute permissions, users, and groups as needed according to the instructions in Assigning Permissions, Users, and Groups to ACLs.

 

---

Modifying a Custom Function Description

Note: You must log in with modify access before you can modify a custom function description. For more information, see Administration Console Security.

You can modify a custom function description to change the logical name of the custom function group or the name of the CFLD file in which the custom function group is declared.

To modify a custom function description:

1. In the left pane, click the Liquid Data node.

2. In the right pane, click the Configuration tab.

3. Click the Custom Functions tab.

   The Administration Console displays a table of custom function descriptions.

4. Click on the custom function description that you want to modify.

5. Change the settings as needed.

6. Click Apply.

 

---

Removing a Custom Function Description

Note: You must log in with modify access before you can remove a custom function description. For more information, see Administration Console Security.

You can remove a custom function description that you no longer need. To remove a custom function description:

1. In the left pane, click the Liquid Data node.

2. In the right pane, click the Configuration tab.

3. Click the Function Library tab.

   The Administration Console displays a table of custom function descriptions.

4. Find the custom function description that you want to remove and click on the trash can on the far right column for that function.

5. When prompted, click Yes to confirm removal.

   The Administration Console removes the selected custom function description.

Note: Removing a Liquid Data custom function description does not remove the JAR or CFLD files associated with the custom function group from your system.To remove these files from the Liquid Data Server repository, see Deleting Folders and Files in the Server Repository.