LIFX Client

Java client to consume LIFX HTTP API.

Usage

The library requires Java 17 or later.

Build the library and install it into the local Maven repository with ./gradlew publishToMavenLocal, then add mavenLocal() to the repositories of your build.gradle file and include the lifx-client dependency as shown below. Building needs a JDK 25 toolchain; Gradle detects an installed one or downloads it automatically.

repositories {
  mavenLocal()
}

dependencies {
  implementation 'com.github.gilbertotcc.lifx:lifx-client:<VERSION>'
}

Sample application

The following example shows how to use LIFX Client to turn on all the lights in red.

To generate the access token, visit LIFX Cloud Settings page.

import static com.github.gilbertotcc.lifx.models.Selectors.all;

import com.github.gilbertotcc.lifx.LifxClient;
import com.github.gilbertotcc.lifx.LifxResult;
import com.github.gilbertotcc.lifx.models.Power;
import com.github.gilbertotcc.lifx.models.Result;
import com.github.gilbertotcc.lifx.models.State;
import com.github.gilbertotcc.lifx.operations.SetLightsStateInput;

import java.util.List;

public class RedLightOnSwitcher {

  public static void main(String[] args) {

    LifxClient client = LifxClient.newLifxClientFor("<YOUR_ACCESS_TOKEN>");

    var state = State.builder()
      .power(Power.ON)
      .color("red")
      .brightness(1.0)
      .build();
    var input = new SetLightsStateInput(all(), state);

    LifxResult<List<Result>> result = client.setLightsState(input);
    if (result instanceof LifxResult.Failure<List<Result>> failure) {
      System.err.println("LIFX call failed: " + failure.lifxCallException().getMessage());
    }
  }
}

Client methods report the outcome of a call through a sealed LifxResult. It is a Success.Some, whose result() holds the result (for setLightsState, the per-light results), a Success.None when LIFX accepts the request without a response body (for example, a fast request answered with 202 Accepted), or a Failure, whose lifxCallException() explains what went wrong. Queries such as listLights report a successful response without a body as a Failure.

A null argument is a programmer error, not a call outcome, so it throws NullPointerException: a client method given a null input, and an *Input constructor given a null value (only the defaultState of SetLightsStatesInput may be null).

When LIFX answers with an error status, the cause of the lifxCallException() is a LifxErrorException with the details: getType(), getStatusCode(), getErrorModel() (the parsed error, or null), getRawBody() and getRateLimit() (the X-RateLimit-* headers, or null). The client doesn't retry, but after a 429 reset() on the rate limit says when the next rate-limit window begins. Check for null first: getRateLimit() is null if LIFX sent no usable rate-limit header, and reset() is null if that header is absent or malformed.

src/integrationTest shows the client calling the real LIFX cloud, and the tests in src/test cover every operation the LIFX HTTP API provides.

Development

./gradlew build compiles the library and runs Checkstyle and the unit tests, which mock the LIFX API with WireMock.

Integration test

./gradlew integrationTest runs LifxClientIntegrationTest against the real LIFX cloud. It is not part of check or build (they only compile and lint its sources) and does not run in CI.

Warning

The test changes the state of your real lights: it switches the power of the first connected light twice, then restores its original power when it ends.

It needs a LIFX personal access token, generated on the LIFX Cloud Settings page, in the LIFX_PAT environment variable; without it the test fails with LIFX_PAT is not set. Gradle does not read .env files (.env is git-ignored, so it is a safe place to keep the token), so export the variable in your shell:

export LIFX_PAT='YOUR_ACCESS_TOKEN'
./gradlew integrationTest

Add -PtestJavaVersion=17 to run it on another JVM (default 25).