Enum HomeError

java.lang.Object
java.lang.Enum<HomeError>
com.codename1.home.HomeError
All Implemented Interfaces:
Comparable<HomeError>
public enum HomeError extends Enum<HomeError>

Typed failure reasons carried by HomeException. Ports map their platform error codes onto these so cross-platform code can branch on a stable value instead of parsing messages.

Crossing the boundary by name, not by ordinal

The native bridges send the Enum.name() of one of these, not its ordinal, and forName(String) resolves it. Ordinals are a wire format that breaks silently: a port built against a build where a constant was inserted in the middle would map every error past the insertion point to the wrong one, and a mis-mapped UNAUTHORIZED looks exactly like a mis-mapped TIMEOUT to everyone downstream. Names cost a few bytes per failure -- and a failure is not the hot path.

  • Enum Constant Details

    • NOT_SUPPORTED

      public static final HomeError NOT_SUPPORTED
      The port, device or OS version has no smart-home support at all, or the requested capability is unavailable on this platform. Returned by every operation on the fallback SmartHome base class.

    • TRAIT_NOT_SUPPORTED

      public static final HomeError TRAIT_NOT_SUPPORTED

      The accessory does not expose this trait, or the backend cannot express it. Distinct from ACCESSORY_NOT_FOUND: the accessory is there and this particular capability is not.

      Some traits can never succeed on a given backend rather than merely being absent from one accessory -- Trait.OUTLET_IN_USE and Trait.TARGET_HUMIDITY have no Matter equivalent at all. The javadoc on each such constant says so.

    • ACCESSORY_NOT_FOUND

      public static final HomeError ACCESSORY_NOT_FOUND
      No accessory with the supplied id is in the graph. Usually means the snapshot the caller is holding is stale; call SmartHome.refresh() and wait for it before reading SmartHome.getStructures() again.

    • ACCESSORY_UNREACHABLE

      public static final HomeError ACCESSORY_UNREACHABLE
      The accessory is in the graph but the platform could not talk to it -- unplugged, out of Thread range, or its bridge is offline. Retryable.

    • UNAUTHORIZED

      public static final HomeError UNAUTHORIZED
      The operation was refused for lack of authorization.

    • AUTHORIZATION_REQUIRED

      public static final HomeError AUTHORIZATION_REQUIRED
      The user has not yet been asked. Recoverable by calling SmartHome.requestAuthorization().

    • SIGN_IN_REQUIRED

      public static final HomeError SIGN_IN_REQUIRED
      No signed-in account. Google Home only: the Home APIs need an account and a per-structure grant before any accessory is visible.

    • RESTRICTED

      public static final HomeError RESTRICTED
      Smart-home access is blocked by parental controls or device management. Not recoverable from inside the app.

    • USER_CANCELED

      public static final HomeError USER_CANCELED
      The user dismissed a platform authorization, setup or commissioning flow.

    • INVALID_ARGUMENT

      public static final HomeError INVALID_ARGUMENT
      A request was rejected before reaching the platform because it was malformed -- an empty write batch, a trait written with the wrong TraitValueKind, a negative timeout.

    • VALUE_OUT_OF_RANGE

      public static final HomeError VALUE_OUT_OF_RANGE

      A write fell outside the range the accessory declares in its TraitConstraint.

      Deliberately an error rather than a clamp. An app that asked for 40 degrees and silently got 38 never learns it was wrong, and the bug surfaces as a user complaint about a thermostat rather than as a failure at the call site.

    • UNIT_MISMATCH

      public static final HomeError UNIT_MISMATCH
      A TraitUnit was supplied that measures a different dimension than the trait requires.

    • READ_ONLY_TRAIT

      public static final HomeError READ_ONLY_TRAIT
      The trait can be read but not written.

    • WRITE_ONLY_TRAIT

      public static final HomeError WRITE_ONLY_TRAIT
      The trait can be written but not read. Rare; some Matter attributes are write-only commands in disguise.

    • PIN_REQUIRED

      public static final HomeError PIN_REQUIRED

      A door lock refused the operation because it requires a PIN and none was supplied. Set one with TraitWrite.setAuthorizationData(java.lang.String).

      Matter locks with RequirePINforRemoteOperation set behave this way. HomeKit never takes a PIN.

    • PIN_REJECTED

      public static final HomeError PIN_REJECTED
      A door lock rejected the supplied PIN.

    • PROVIDER_UNAVAILABLE

      public static final HomeError PROVIDER_UNAVAILABLE
      The platform's smart-home provider is not installed -- Google Play services on Android. Recoverable via SmartHome.openProviderSetup().

    • PROVIDER_UPDATE_REQUIRED

      public static final HomeError PROVIDER_UPDATE_REQUIRED
      The installed provider is too old. Also recoverable via SmartHome.openProviderSetup().

    • NOT_CONFIGURED

      public static final HomeError NOT_CONFIGURED
      The app is missing build configuration the backend needs -- an entitlement, a project id, an OAuth client. Always accompanied by HomeConfigurationException and by text from SmartHome.getConfigurationProblems() naming what is missing.

    • COMMISSIONING_FAILED

      public static final HomeError COMMISSIONING_FAILED
      Commissioning ran and did not add the accessory. The message carries the platform's own text.

    • COMMISSIONING_UNAVAILABLE

      public static final HomeError COMMISSIONING_UNAVAILABLE
      This platform cannot commission at all -- watchOS, tvOS, macOS, or an Android device with no Play services.

    • ECOSYSTEM_APP_MISSING

      public static final HomeError ECOSYSTEM_APP_MISSING
      The ecosystem app a flow needs -- Apple Home, Google Home -- is not installed, so there was nothing to hand off to.

    • RATE_LIMITED

      public static final HomeError RATE_LIMITED
      The platform rate-limited the request.

    • BUSY

      public static final HomeError BUSY
      The platform refused because an operation of this kind is already in flight. Retryable once it settles.

    • TIMEOUT

      public static final HomeError TIMEOUT
      The operation did not complete within its safety timeout.

    • INVALID_DATA

      public static final HomeError INVALID_DATA
      A payload could not be decoded -- a malformed Matter setup payload, a platform value the port could not map onto a TraitValue. Never surfaces as an unchecked exception from a parser.

    • UNKNOWN

      public static final HomeError UNKNOWN
      Anything the port could not classify. The message carries the platform's own text.

  • Method Details

    • values

      public static HomeError[] values()
      Returns an array containing the constants of this enum type, in the order they are declared.
      Returns:
      an array containing the constants of this enum type, in the order they are declared

    • valueOf

      public static HomeError valueOf(String name)
      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum type has no constant with the specified name
      NullPointerException - if the argument is null

    • forName

      public static HomeError forName(String name)

      Resolves a constant by name, total: an unrecognized or null name answers UNKNOWN rather than throwing.

      This exists so the boundary cannot throw. Enum.valueOf raises IllegalArgumentException on an unknown name, and the one place this is called is while decoding a failure that has already happened -- so the throw would replace a real error the caller could act on with an unrelated one they cannot. A port from a newer build naming an error this one does not have degrades to UNKNOWN with the platform text intact.

      Parameters
      Returns

      the matching constant, or UNKNOWN