> ## Documentation Index
> Fetch the complete documentation index at: https://docs-test.symmetry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Java SDK quickstart

> Embed the STE native library and calculate withholding for one employee with the Java SDK.

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.

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

## Prerequisites

<Steps>
  <Step title="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.
  </Step>

  <Step title="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](/ste/operations/linking-the-native-library) for the per-platform details (`LD_LIBRARY_PATH`, rpath, or `PATH`).
  </Step>
</Steps>

## Calculate

```java theme={null}
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.                   |

<Tip>
  `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.
</Tip>

## 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](/ste/operations/handles-and-pooling).

## Next steps

<Columns cols={2}>
  <Card title="Full calculation walkthrough" href="/ste/calculation-walkthroughs/java-sdk" icon="list-check">
    Install the interface and run a complete, realistic pay calc end to end.
  </Card>

  <Card title="Configuring a calculation" href="/ste/configuration/setting-jurisdictions" icon="sliders">
    Wages, jurisdictions, benefits, and engine options in depth.
  </Card>

  <Card title="Migrating from STE1-style" href="/ste/migration/ste1-to-ste2" icon="arrow-right-arrow-left">
    Map legacy per-tax setters onto STE2-style calls.
  </Card>
</Columns>