Java SDK quickstart - Symmetry Docs

The Java SDK wraps the native STE library and exposes a single entry class, STEPayrollCalculator, in the com.symmetry.ste package. This quickstart runs a federal + California state calculation for one employee using the modern STE2-style configuration.

STE2-style configures every tax through two calls — setJurisdictionData(...) and setJurisdictionMiscellaneousParms(...) — using a uniqueTaxID. Prefer this over the legacy per-tax setters (setFederalParameters, setStateParameters, …).

Prerequisites

Get the SDK and tax database

You need the STE JAR, the native library for your platform (libste.so / libste.dylib / ste.dll), and an STE home directory that contains the tax database. These are provided with your STE license.

Put the native library on the load path

The JAR loads the native library at runtime. Make sure it’s discoverable — see Linking the native library for the per-platform details (LD_LIBRARY_PATH, rpath, or PATH).

Calculate

import com.symmetry.ste.*;
import java.text.SimpleDateFormat;

public class HelloPayroll {
    public static void main(String[] args) throws Exception {
        // 1. Initialize the engine against your STE home directory.
        STEPayrollCalculator ste = new STEPayrollCalculator("/opt/symmetry/ste");

        try {
            // 2. Start clean for this employee.
            ste.clearPayrollCalculations();
            ste.clearSettings();

            // 3. Describe the pay run: biweekly, 12th period of the year.
            SimpleDateFormat fmt = new SimpleDateFormat("yyyy-MM-dd");
            ste.setPayrollRunParameters(fmt.parse("2026-06-15"), 26, 12);

            String federalLoc = "00-000-0000";
            String stateLoc   = "06-000-0000";              // California
            String fitTaxId   = "00-000-0000-FIT-000";      // Federal income tax
            String sitTaxId   = "06-000-0000-SIT-000";      // California SIT
            Money zero = Money.zero();
            Rate  zeroRate = new Rate(0.0);

            // 4. Wages: $4,000 gross, 80 hours, at both the federal and state locations.
            ste.setCalculationMethod(federalLoc, CalcMethod.ANNUALIZED, CalcMethod.NONE);
            ste.setCalculationMethod(stateLoc,   CalcMethod.ANNUALIZED, CalcMethod.NONE);
            ste.setWages(federalLoc, WageType.REGULAR, new Hours(80), new Money(4000), zero, zero, zero);
            ste.setWages(stateLoc,   WageType.REGULAR, new Hours(80), new Money(4000), zero, zero, zero);

            // 5. Federal income tax (STE2): jurisdiction + withholding elections.
            ste.setJurisdictionData(fitTaxId, federalLoc, false, true,
                zero, zero, zero, zero, zero,
                JurisdictionRounding.DEFAULT, false, false,
                zeroRate, zero, zeroRate, zero);
            ste.setJurisdictionMiscellaneousParms(fitTaxId, "FILINGSTATUS", "S");
            ste.setJurisdictionMiscellaneousParms(fitTaxId, "TOTALALLOWANCES", 0);

            // 6. California SIT (STE2).
            ste.setJurisdictionData(sitTaxId, stateLoc, false, true,
                zero, zero, zero, zero, zero,
                JurisdictionRounding.DEFAULT, false, false,
                zeroRate, zero, zeroRate, zero);
            ste.setJurisdictionMiscellaneousParms(sitTaxId, "FILINGSTATUS", "S");
            ste.setJurisdictionMiscellaneousParms(sitTaxId, "TOTALALLOWANCES", "0");

            // 7. Calculate.
            ste.calculateTaxes();

            // 8. Read the withholding per tax.
            Money fit = ste.getJurisdictionCalculation(fitTaxId, WageType.REGULAR).getTax();
            Money sit = ste.getJurisdictionCalculation(sitTaxId, WageType.REGULAR).getTax();
            System.out.println("Federal income tax: " + fit);
            System.out.println("California SIT:     " + sit);
        } finally {
            // 9. Release native resources.
            ste.close();
        }
    }
}

What each step does

Step	Call	Purpose
Init	`new STEPayrollCalculator(steHome)`	Opens an engine handle against the tax database.
Reset	`clearPayrollCalculations()`, `clearSettings()`	Clears prior state so the handle is reusable.
Pay run	`setPayrollRunParameters(date, ppy, period)`	Pay date, periods per year, and current period.
Wages	`setCalculationMethod(...)`, `setWages(...)`	Method (Annualized/Flat) and gross/hours by location.
Jurisdiction	`setJurisdictionData(uniqueTaxID, …)`	Configures one tax; residency, rounding, overrides.
Elections	`setJurisdictionMiscellaneousParms(uniqueTaxID, name, value)`	Filing status, allowances, and other W-4-style inputs.
Calculate	`calculateTaxes()`	Runs the employee pass.
Read	`getJurisdictionCalculation(uniqueTaxID, wageType).getTax()`	The amount to withhold for that tax.

setWages takes gross by period bucket: (hours, ctd, mtd, qtd, ytd). Use Money.zero() for buckets you’re not tracking. The typed wrappers (Money, Hours, Rate) prevent unit mix-ups.

Handles, threads, and pooling

An STEPayrollCalculator handle is not thread-safe — use one handle per thread. Initialization has a cost, so for high volume you reuse handles rather than creating one per calculation. See Handles & pooling.

Next steps

Full calculation walkthrough

Install the interface and run a complete, realistic pay calc end to end.

Configuring a calculation

Wages, jurisdictions, benefits, and engine options in depth.

Migrating from STE1-style

Map legacy per-tax setters onto STE2-style calls.

​Prerequisites

​Calculate

​What each step does

​Handles, threads, and pooling

​Next steps

Full calculation walkthrough

Configuring a calculation

Migrating from STE1-style

Prerequisites

Calculate

What each step does

Handles, threads, and pooling

Next steps