Maven dependency

		<dependency>
			<groupId>net.officefloor.springboot</groupId>
			<artifactId>officefloor-rest-spring-boot-4-starter</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

Application class

@SpringBootApplication
public class SpringRestManagedObjectApplication {

	public static void main(String[] args) {
		SpringApplication.run(SpringRestManagedObjectApplication.class, args);
	}
}

Scopes

The scope field in the YAML controls how long one instance lives and which parts of the request pipeline share it:

Both examples in this tutorial use PROCESS scope: a new instance is created when each request arrives and shared across every step that handles that request.

Example 1 — class: (ClassManagedObjectSource)

The class: YAML shorthand delegates to ClassManagedObjectSource, which instantiates the named class with its default constructor. This is the right choice for a plain POJO that needs no flows or asynchronous behaviour.

public class RequestContext {

	private final String correlationId = UUID.randomUUID().toString();

	private final Instant startTime = Instant.now();

	public String getCorrelationId() {
		return correlationId;
	}

	public Instant getStartTime() {
		return startTime;
	}
}

managed-object:
  class: net.officefloor.tutorial.springrestmanagedobject.RequestContext
  scope: PROCESS

public class RequestContextService {

	public void service(RequestContext context, ObjectResponse<RequestContextResponse> response) {
		response.send(new RequestContextResponse(
				context.getCorrelationId(),
				context.getStartTime().toEpochMilli()));
	}
}

service:
  class: net.officefloor.tutorial.springrestmanagedobject.RequestContextService

@Data
@NoArgsConstructor
@AllArgsConstructor
public class RequestContextResponse {

	private String correlationId;
	private long startTimeMs;
}

{
  "correlationId" : "a3f9c2d1-7b4e-4f0a-9c6d-e1b2f3a4d5e6",
  "startTimeMs"   : 1749200000000
}

Example 2 — source: (custom AbstractManagedObjectSource)

When a managed object needs to declare flows or perform asynchronous setup, implement AbstractManagedObjectSource directly and reference the class via source: in the YAML. None is used as the type parameter for the dependency keys when the source has no dependencies.

public class SessionId {

	private final String id = UUID.randomUUID().toString();

	public String getId() {
		return id;
	}
}

public class SessionIdSource extends AbstractManagedObjectSource<None, SessionIdSource.Flows> {

	public enum Flows {
		LOG
	}

	@Override
	protected void loadSpecification(SpecificationContext context) {
	}

	@Override
	protected void loadMetaData(MetaDataContext<None, Flows> context) throws Exception {
		// Declare the type this source provides
		context.setObjectClass(SessionId.class);

		// Declare the LOG flow: argument is the session ID string to be logged.
		// Wire this flow via  outputs: LOG: <function-name>  in the YAML to connect
		// it to a downstream function.  The source triggers it via
		// ManagedObjectExecuteContext.invokeStartupProcess() or the managed object
		// signals it via ManagedObjectUser.setManagedObject() for async completion.
		context.addFlow(Flows.LOG, String.class);
	}

	@Override
	protected ManagedObject getManagedObject() throws Throwable {
		SessionId sessionId = new SessionId();
		return () -> sessionId;
	}
}

public class SessionLogService {

	public void log(@Parameter String sessionId) {
		// In production: write to audit log, metrics, distributed trace, etc.
		// The source triggers this function via ManagedObjectExecuteContext,
		// passing the session ID as the typed flow argument.
	}
}

managed-object:
  source: net.officefloor.tutorial.springrestmanagedobject.SessionIdSource
  scope: PROCESS
  outputs:
    LOG: logSession

logSession:
  class: net.officefloor.tutorial.springrestmanagedobject.SessionLogService

public class SessionIdService {

	public void service(SessionId sessionId, ObjectResponse<String> response) {
		response.send(sessionId.getId());
	}
}

service:
  class: net.officefloor.tutorial.springrestmanagedobject.SessionIdService

Testing

@SpringBootTest
@AutoConfigureMockMvc
public class SpringRestManagedObjectHttpServerTest {

	@Autowired
	private MockMvc mvc;

	@Autowired
	private ObjectMapper mapper;

	// --- class: (ClassManagedObjectSource) example ---

	@Test
	public void requestContextIsPopulated() throws Exception {
		mvc.perform(get("/request").accept(MediaType.APPLICATION_JSON))
				.andExpect(status().isOk())
				.andExpect(jsonPath("$.correlationId").isString())
				.andExpect(jsonPath("$.startTimeMs").isNumber());
	}

	@Test
	public void eachRequestGetsFreshManagedObjectInstance() throws Exception {
		MvcResult first = mvc.perform(get("/request").accept(MediaType.APPLICATION_JSON))
				.andExpect(status().isOk())
				.andReturn();
		MvcResult second = mvc.perform(get("/request").accept(MediaType.APPLICATION_JSON))
				.andExpect(status().isOk())
				.andReturn();

		RequestContextResponse r1 = mapper.readValue(
				first.getResponse().getContentAsString(), RequestContextResponse.class);
		RequestContextResponse r2 = mapper.readValue(
				second.getResponse().getContentAsString(), RequestContextResponse.class);

		assertNotNull(r1.getCorrelationId(), "correlationId must be present");
		assertNotNull(r2.getCorrelationId(), "correlationId must be present");

		// PROCESS scope: each incoming request gets a new managed object instance,
		// so the correlation IDs generated at construction time must differ.
		assertNotEquals(r1.getCorrelationId(), r2.getCorrelationId(),
				"PROCESS-scoped managed object must be a new instance per request");
	}

	@Test
	public void startTimeIsReasonable() throws Exception {
		long before = System.currentTimeMillis();
		MvcResult result = mvc.perform(get("/request").accept(MediaType.APPLICATION_JSON))
				.andExpect(status().isOk())
				.andReturn();
		long after = System.currentTimeMillis();

		RequestContextResponse response = mapper.readValue(
				result.getResponse().getContentAsString(), RequestContextResponse.class);

		assertTrue(response.getStartTimeMs() >= before,
				"startTimeMs must be at or after the request was sent");
		assertTrue(response.getStartTimeMs() <= after,
				"startTimeMs must be at or before the response was received");
	}

	// --- source: (custom ManagedObjectSource) example ---

	@Test
	public void customManagedObjectSourceIsInjected() throws Exception {
		mvc.perform(get("/session"))
				.andExpect(status().isOk());
	}

	@Test
	public void customManagedObjectSourceProvidesUniqueInstancePerRequest() throws Exception {
		String id1 = mvc.perform(get("/session"))
				.andExpect(status().isOk())
				.andReturn().getResponse().getContentAsString();
		String id2 = mvc.perform(get("/session"))
				.andExpect(status().isOk())
				.andReturn().getResponse().getContentAsString();

		assertNotNull(id1, "session ID must be present");
		assertNotNull(id2, "session ID must be present");

		// PROCESS scope: SessionIdSource creates a new SessionId per request,
		// so two successive requests must carry different IDs.
		assertNotEquals(id1, id2,
				"Custom ManagedObjectSource with PROCESS scope must provide a new instance per request");
	}
}

The class: tests confirm that PROCESS scope delivers a freshly-constructed RequestContext per request — two successive calls produce different correlation IDs — and that the start timestamp falls within the wall-clock window of the request.

The source: tests confirm that SessionIdSource is wired correctly — the endpoint responds successfully — and that PROCESS scope gives each request a distinct SessionId instance.

What you have now

After completing this tutorial you can:

• Understand that the primary value of ManagedObjectSource is enabling flows and asynchronous completion managed by the OfficeFloor framework
• Use the class: shorthand (backed by ClassManagedObjectSource) for plain POJOs that need no flows
• Extend AbstractManagedObjectSource with None for unused key parameters, and declare flow outputs via context.addFlow()
• Wire flows to handler functions in the YAML via outputs: and receive typed arguments via @Parameter
• Choose PROCESS, THREAD, or FUNCTION scope to match the intended lifetime: per-request, per-thread-within-request, or per-function-step
• Inject any managed object into service methods by type, alongside Spring beans, with no annotation required on either the class or the method