Tutorial: Creating a Numeric Boolean Value Processor

In this tutorial you will build a complete, working value processor that converts a numeric column storing 1 (true) and 0 (false) into a proper SQL BOOLEAN type. The project is built with Apache Maven, which handles the compile-time dependency on BBjStartup.jar and produces a ready-to- deploy JAR in one command. By the end you will have:

• Created the ORDERS table in the ChileCompany database using the Enterprise Manager SQL console.
• Created a Maven project with the correct structure and pom.xml.
• Written the ValueProcessor Java class.
• Written the ValueProcessorBBjSQLFactory Java class.
• Built the project and located the output JAR.
• Registered the JAR with BBj as a Session Specific Classpath (SSCP).
• Configured the database SQL_FACTORY and SQL_FACTORY_SSCP properties.
• Assigned the processor to a column via a type definition in Enterprise Manager.
• Verified the result with SQL queries.

STEPS IN THIS TUTORIAL

The Scenario

In this tutorial you will work with a table called ORDERS that has a column called IS_SHIPPED defined as a numeric field (NUMERIC(1)). The application stores 1 when an order has shipped and 0 when it has not. Without a value processor, a SQL query must compare against raw numbers:

SELECT ORDER_ID, IS_SHIPPED FROM ORDERS WHERE IS_SHIPPED = 1

This works, but it exposes the raw storage detail to every caller. After applying a value processor you will be able to use a proper SQL boolean literal instead:

SELECT ORDER_ID, IS_SHIPPED FROM ORDERS WHERE IS_SHIPPED = TRUE

The IS_SHIPPED column will be reported as BOOLEAN in JDBC metadata, and result set values will be true or false rather than 1 or 0. The first step below creates this table so you have a real target to configure the processor against.

Create the ORDERS Table

CREATE TABLE ORDERS (ORDER_ID INTEGER PRIMARY KEY, IS_SHIPPED NUMERIC(1))

This creates the ORDERS table with two columns: an integer primary key and a single-digit numeric column that will store 1 (shipped) or 0 (not shipped). This is the column you will attach the value processor to in later steps.

Create the Maven Project Structure

Run the following command in a terminal to generate the project. Maven will prompt you to confirm the settings; press Enter to accept each default.

mvn archetype:generate \
  -DgroupId=com.example.sql.valueprocessor \
  -DartifactId=myprocessors \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DarchetypeVersion=1.5 \
  -DinteractiveMode=false

This creates a directory called myprocessors with a skeleton pom.xml and a sample Java source file.

Before continuing, delete both generated sample files — the tutorial's pom.xml does not include JUnit dependencies, so AppTest.java will fail to compile if left in place:

• src/main/java/com/example/sql/valueprocessor/App.java
• src/test/java/com/example/sql/valueprocessor/AppTest.java

You will replace App.java with your processor class in Step 4.

Install BBjStartup.jar into the Local Maven Repository

BBjStartup.jar is not published to Maven Central, so you need to install it into your local Maven repository (~/.m2/repository) manually. This only needs to be done once per development machine, or whenever you update your BBj installation.

Run the following command, replacing /path/to/BBj/.lib/BBjStartup.jar with the actual path on your system:

mvn install:install-file \
  -Dfile=/path/to/BBj/.lib/BBjStartup.jar \
  -DgroupId=com.basis \
  -DartifactId=BBjStartup \
  -Dversion=1.0 \
  -Dpackaging=jar

The values for -DgroupId, -DartifactId, and -Dversion are local identifiers that you choose. They only need to match what you reference in your pom.xml in the next step. The values shown here (com.basis:BBjStartup:1.0) are used throughout this tutorial.

Write the pom.xml

Replace the contents of myprocessors/pom.xml with the following. Each section is explained in the comments and in the table below.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             https://maven.apache.org/xsd/maven-4.0.0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <!-- ── Project identity ─────────────────────────────────────── -->
  <groupId>com.example.sql.valueprocessor</groupId>
  <artifactId>myprocessors</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>
  <name>My BBj Value Processors</name>

  <properties>
    <!-- Match the Java version required by your BBj installation. -->
    <maven.compiler.source>21</maven.compiler.source>
    <maven.compiler.target>21</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencies>

    <!-- ── BBjStartup.jar ────────────────────────────────────────
         Provides ValueProcessor and BBjSQLLiteral.
         scope=provided means Maven uses it for compilation only;
         it will NOT be bundled inside the output JAR.
         The coordinates here must match what you used in Step 3.
    ────────────────────────────────────────────────────────────── -->
    <dependency>
      <groupId>com.basis</groupId>
      <artifactId>BBjStartup</artifactId>
      <version>1.0</version>
      <scope>provided</scope>
    </dependency>

  </dependencies>

  <build>
    <!-- Controls the output JAR filename. -->
    <finalName>myprocessors</finalName>

    <plugins>

      <!-- Pin the JAR plugin version explicitly. -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.4.2</version>
      </plugin>

    </plugins>
  </build>

</project>

Key points about this POM:

Write the ValueProcessor Class

Create the file src/main/java/com/example/sql/valueprocessor/NumericBooleanValueProcessor.java inside your myprocessors project directory and paste in the following source:

package com.example.sql.valueprocessor;

import java.sql.SQLException;
import java.sql.Types;

import com.basis.startup.type.sql.BBjSQLLiteral;
import com.basis.startup.type.sql.ValueProcessor;

/**
 * Converts a numeric column that stores 1 (true) or 0 (false)
 * to and from a SQL BOOLEAN value.
 *
 * Raw storage: N(1) field containing the integer 1 or 0.
 * SQL type:    BOOLEAN (java.lang.Boolean).
 */
public class NumericBooleanValueProcessor extends ValueProcessor
{
    /**
     * Public default constructor required by the BBj SQL engine,
     * which instantiates this class via reflection.
     */
    public NumericBooleanValueProcessor()
    {
        // No initialisation needed.
    }

    /**
     * Converts the raw numeric value from the data file to a Boolean.
     *
     * The raw value will be a Number (e.g. Integer, Double, BigDecimal)
     * for a numeric field.  Any non-zero value is treated as true;
     * zero, null, and empty are treated as false.
     */
    @Override
    public Object computeReturnedValue(Object p_value) throws SQLException
    {
        if (p_value == null)
        {
            return Boolean.FALSE;
        }

        String str = p_value.toString().trim();
        if (str.isEmpty())
        {
            return Boolean.FALSE;
        }

        try
        {
            return Integer.parseInt(str) != 0;
        }
        catch (NumberFormatException e)
        {
            throw new SQLException(
                "NumericBooleanValueProcessor: cannot convert value \""
                + str + "\" to a boolean.",
                e);
        }
    }

    /**
     * Converts a SQL BOOLEAN value back to the raw numeric form (1 or 0)
     * to be written to the data file.
     */
    @Override
    public Object computeRawValue(BBjSQLLiteral p_value) throws SQLException
    {
        if (p_value == null || p_value.isNull())
        {
            return Integer.valueOf(0);
        }

        return p_value.getBoolean() ? Integer.valueOf(1) : Integer.valueOf(0);
    }

    /**
     * Reports this column as a SQL BOOLEAN type to JDBC clients.
     */
    @Override
    public int getSqlType()
    {
        return Types.BOOLEAN;
    }

    /**
     * Name shown in Enterprise Manager when selecting a value processor.
     */
    @Override
    public String getDisplayName()
    {
        return "Boolean 1/0 Numeric Processor";
    }

    /**
     * Description shown alongside the display name in Enterprise Manager.
     */
    @Override
    public String getDescription()
    {
        return "Converts a numeric field storing 1 (true) or 0 (false) "
             + "to and from a SQL BOOLEAN value.";
    }

    /**
     * Returns true because the numeric values 0 and 1 sort in the same
     * order as false and true, so existing numeric indexes remain usable
     * for range query optimisation.
     */
    @Override
    public boolean isLexicallyOrdered()
    {
        return true;
    }
}

Walk-through of the key decisions in this implementation:

Your project directory should now look like this:

myprocessors/
├── pom.xml
└── src/
    └── main/
        └── java/
            └── com/
                └── example/
                    └── sql/
                        └── valueprocessor/
                            └── NumericBooleanValueProcessor.java

Write the ValueProcessorBBjSQLFactory Class

The BBj SQL engine does not automatically scan your JAR for processor classes at query time. Instead, it looks for a ValueProcessorBBjSQLFactory implementation whose class name is registered in the database's SQL_FACTORY property. This factory class is responsible for advertising your processor(s) to the engine.

Create a new file src/main/java/com/example/sql/valueprocessor/NumericBooleanProcessorFactory.java:

package com.example.sql.valueprocessor;

import com.basis.startup.type.sql.ValueProcessor;
import com.basis.startup.type.sql.ValueProcessorBBjSQLFactory;
import java.util.Collection;
import java.util.List;

/**
 * Factory that advertises NumericBooleanValueProcessor to the BBj SQL engine.
 *
 * The fully-qualified name of this class is what you enter in the
 * database's SQL_FACTORY property in Enterprise Manager:
 *   com.example.sql.valueprocessor.NumericBooleanProcessorFactory
 */
public class NumericBooleanProcessorFactory implements ValueProcessorBBjSQLFactory
{
    /**
     * Public default constructor required by the BBj SQL engine,
     * which instantiates this class via reflection.
     */
    public NumericBooleanProcessorFactory()
    {
    }

    /**
     * Returns all ValueProcessor implementations provided by this factory.
     * The SQL engine calls this to populate the processor dropdown in the
     * Enterprise Manager type definition editor.
     */
    @Override
    public Collection<ValueProcessor> getValueProcessors()
    {
        return List.of(new NumericBooleanValueProcessor());
    }
}

Key points about this class:

Your project source tree should now look like this:

myprocessors/
├── pom.xml
└── src/
    └── main/
        └── java/
            └── com/
                └── example/
                    └── sql/
                        └── valueprocessor/
                            ├── NumericBooleanProcessorFactory.java
                            └── NumericBooleanValueProcessor.java

Build the Project and Locate the JAR

From a terminal, change into the myprocessors project root directory (the directory that contains pom.xml) and run:

cd myprocessors
mvn clean package

Maven will compile the source, run any tests, and assemble the JAR. A successful build ends with output similar to:

[INFO] BUILD SUCCESS
[INFO] -----------------------------------------------
[INFO] Total time:  3.142 s
[INFO] Finished at: 2026-03-03T10:00:00

Where to find the output JAR

Maven writes the output JAR to the target/ subdirectory inside your project root. Because you set <finalName>myprocessors</finalName> inside <build> in the POM, the file is named:

myprocessors/target/myprocessors.jar

You can verify the contents of the JAR to confirm no BBj classes were accidentally included:

jar tf target/myprocessors.jar

Expected output — only your class and Maven metadata should be listed:

META-INF/
META-INF/MANIFEST.MF
com/example/sql/valueprocessor/NumericBooleanValueProcessor.class

Deploy the JAR to the BBj Server

Copy target/myprocessors.jar to a location on the BBj server machine that BBj can read. A common convention is a custom subdirectory under the BBj installation directory:

cp target/myprocessors.jar /usr/local/basis/lib/custom/myprocessors.jar

Note and record the full absolute path; you will need it when creating the SSCP entry in the next step.

Create an SSCP in Enterprise Manager

A Session Specific Classpath (SSCP) is a named classpath record that BBj uses to locate external classes at runtime. You need one SSCP that includes your JAR.

• Open Enterprise Manager and log in to your BBj server.

• In the left-hand navigation tree, expand BBjServices and select Java Settings.

• Click add (the "+" button) to create a new classpath entry.

• Enter a Name for the classpath. For this tutorial, use myprocessors.

• Add a new classpath entry (click the "+" button in the upper right corner) and select JAR File(s) and then locate the JAR you deployed in Step 7:

  /usr/local/basis/lib/custom/myprocessors.jar

• Click the Save button.

Set the Database SQL_FACTORY and SQL_FACTORY_SSCP Properties

Two database properties must be set to wire your factory into the database. Both are found under the Custom Functionality category in the database properties view.

• In the Enterprise Manager navigation tree, expand Databases and select the database that contains your ORDERS table.

• Select the Settings tab.

• Find the Custom Functionality section in the properties panel.

• Locate the field labelled BBjSQLFactory Implementation and set its value to the fully-qualified class name of your factory:

com.example.sql.valueprocessor.NumericBooleanProcessorFactory

• Locate the field labelled Scalar/Group Function SSCP and set its value to the SSCP name you created in Step 9:

myprocessors

• Click Save.

Create a Type Definition

A Type Definition is a named schema object in the BBj data dictionary that can carry a value processor class reference. You will create one specifically for your numeric boolean column.

• In Enterprise Manager, with your database selected, navigate to the Types tab.

• Click add (the “+” button) to create a new type definition.

• Set the following properties:

• Click Save.

Assign the Type Definition to the Column

Link the BOOLEAN_NUMERIC type definition to the IS_SHIPPED column in your ORDERS table.

• On the Tables tab, double-click on the ORDERS table (you may need to click the refresh button to see the new table).

• Select the Columns tab.

• Select the IS_SHIPPED column in the column list.

• In the column's properties panel, find the Data Type field and select BOOLEAN_NUMERIC from the dropdown.

• Click Save.

Verify the Result

Select the SQL tab at the bottom of the page and run the following query to confirm the processor is working correctly.

Verify SELECT returns Boolean values

SELECT ORDER_ID, IS_SHIPPED
FROM   ORDERS

The IS_SHIPPED column should now return true or false instead of 1 or 0.

Verify filtering with Boolean literals

-- Find all orders that have shipped
SELECT ORDER_ID FROM ORDERS WHERE IS_SHIPPED = TRUE

-- Find all orders that have not shipped
SELECT ORDER_ID FROM ORDERS WHERE IS_SHIPPED = FALSE

Both queries should return correct results without any raw numeric comparisons.

Verify writing (UPDATE)

UPDATE ORDERS
SET    IS_SHIPPED = TRUE
WHERE  ORDER_ID = 1

After the UPDATE, re-select the row. IS_SHIPPED should return true. The underlying data file stores the integer 1, confirming that computeRawValue() converted the boolean correctly.

Summary of Steps

See Also

SQL Custom Value Processors – Overview

Custom Value Processors – Reference

java/sql/Types

Java Settings

Databases