Package io.github.jspinak.brobot.navigation.service

package io.github.jspinak.brobot.navigation.service
Service layer for state and transition management.

This package provides service interfaces for accessing and managing states and transitions within the Brobot framework. These services act as the primary API for other components to interact with the state model, ensuring consistent access patterns and centralized management of the automation structure.

Core Services

  • StateService - Comprehensive state management including CRUD operations and queries
  • StateTransitionService - Manages transition definitions and relationships between states

Service Responsibilities

StateService

Primary interface for state operations:

  • State retrieval by ID, name, or enum
  • Bulk state operations
  • Name-to-ID resolution
  • State persistence and lifecycle
  • Visit counter management

StateTransitionService

Manages transition relationships:

  • Transition registration and storage
  • Transition query by state pairs
  • Relationship mapping maintenance
  • Transition availability checking

Usage Examples

State Operations


 StateService stateService = context.getBean(StateService.class);

 // Retrieve state by name
 Optional<State> loginState = stateService.findByName("LoginScreen");

 // Get state ID from name
 Long stateId = stateService.getStateId("Dashboard");

 // Retrieve multiple states
 Set<State> states = stateService.getStates("Login", "Dashboard", "Settings");

 // Save new state
 State newState = new State.Builder()
     .withName("NewFeature")
     .build();
 stateService.save(newState);

 // Reset visit counters for fresh run
 stateService.resetTimesVisited();

Transition Management


 StateTransitionService transitionService =
     context.getBean(StateTransitionService.class);

 // Register new transition
 StateTransition loginTransition = new StateTransition.Builder()
     .setFromState(loginScreen)
     .setToState(dashboard)
     .build();
 transitionService.add(loginTransition);

 // Query transitions
 Set<StateTransition> fromLogin =
     transitionService.getTransitionsFrom(loginId);

 // Check if direct transition exists
 boolean canTransition =
     transitionService.hasTransition(currentId, targetId);

State Discovery


 // Find all states that can reach target
 Set<Long> predecessors = transitionService
     .getStatesWithTransitionsTo(targetId);

 // Find all states reachable from current
 Set<Long> successors = transitionService
     .getStatesWithTransitionsFrom(currentId);

 // Get complete state graph information
 Map<Long, Set<Long>> stateGraph = transitionService
     .getCompleteTransitionMap();

Service Design Patterns

Repository Pattern

Services delegate to underlying repositories:

  • StateService uses StateStore
  • StateTransitionService uses transition storage
  • Provides abstraction over storage details

Optional Returns

Services use Optional for potentially missing data: 


 Optional<State> state = stateService.findByName("MayNotExist");
 state.ifPresent(s -> {
     // Process state
 });

Bulk Operations

Services support efficient bulk operations: 


 // Get multiple states in one call
 Set<State> states = stateService.getStates(stateIds);

 // Add multiple transitions
 transitionService.addAll(transitionList);

State Identification

Services support multiple identification methods:

  • State ID (Long) - Internal numeric identifier
  • State Name (String) - Human-readable name
  • State Enum - Type-safe enum reference 

 // By ID
 State byId = stateService.get(123L);

 // By name
 State byName = stateService.findByName("LoginScreen").orElseThrow();

 // By enum
 State byEnum = stateService.get(States.LOGIN_SCREEN);

Performance Considerations

  • Services may cache frequently accessed data
  • Bulk operations reduce round trips
  • Lazy loading for complex state objects
  • Efficient indexing for name lookups

Thread Safety

Services are designed for concurrent access:

  • Thread-safe read operations
  • Synchronized write operations where needed
  • Immutable return values where possible

Best Practices

  1. Always check Optional returns before using values
  2. Use bulk operations when dealing with multiple items
  3. Cache service references rather than repeated lookups
  4. Handle missing states gracefully
  5. Use appropriate identification method for context

Integration

Services are used throughout the framework:

  • PathFinder uses services to resolve state names
  • TransitionExecutor queries transition availability
  • StateNavigator relies on both services
  • Monitoring components query active states
Since:
1.0
See Also:
  • Classes
    Class
    Description
    StateService
    Service layer for managing states within the active project.
    StateTransitionService
    Service layer for managing state transitions within the active project.