Core Concepts
Instance Creation
Soklet must create and provide instances of types that contain Resource Methods on your behalf. To do this, it delegates to the InstanceProvider::provide(Class<?>) method of your configured InstanceProvider.
// Soklet will ask its InstanceProvider to instantiate ExampleResource
public class ExampleResource {
@GET("/")
public String index() {
return "Hello, world!";
}
}
// Soklet will ask its InstanceProvider to instantiate ExampleResource
public class ExampleResource {
@GET("/")
public String index() {
return "Hello, world!";
}
}
Further, if Soklet encounters a Resource Method Parameter that it does not know how to inject - one of your application-specific types, for example - it will ask for an instance of it via InstanceProvider::provide(Parameter):
@POST("/lottery")
public boolean playLottery(
@QueryParameter List<String> numbers,
LotteryBackend lotteryBackend // vended by your InstanceProvider
) {
return lotteryBackend.isWinner(numbers);
}
@POST("/lottery")
public boolean playLottery(
@QueryParameter List<String> numbers,
LotteryBackend lotteryBackend // vended by your InstanceProvider
) {
return lotteryBackend.isWinner(numbers);
}
For a list of all Resource Method Parameter types that Soklet will inject by default, see Default Injections.
Why is this useful?
By delegating instance provisioning to code you can control, Soklet gives you the ability to construct arbitrarily complex objects. This is in contrast to frameworks which require your types to be warped to conform to instantiation rules, e.g. "must have a default constructor" or "everything is static".
Further, if you use a Dependency Injection library, it's easy to plug it in, making Soklet use the same plumbing the rest of your app already does. The simplicity of a consistent app-wide instantiation approach together with the effectiveness of modern DI tooling is a powerful combination.
Specifying an Instance Provider
Route discovery is separate from instance creation. The default ResourceMethodResolver::fromClasspathIntrospection resolver is a singleton for the class loader that defines Soklet. Its first resource-method resolution uses that thread's context class loader and permanently caches the route table or failure. Changing the context class loader later does not rediscover routes. Applications sharing Soklet through a parent loader, hosting multiple application loaders, or supporting hot reload should configure a separate explicit fromClasses(...) or fromMethods(...) resolver for each application. A custom InstanceProvider alone does not change that discovery lifetime.
Soklet applications use InstanceProvider::defaultInstance out-of-the-box. It requires a concrete class with a no-argument constructor accessible to Soklet, normally a public class and public constructor. HTTP/SSE setup checks resource classes before accepting requests, without constructing them. A custom provider retains control of construction, including constructor injection; that default-constructor check does not apply to it. Declare routes directly on the public concrete resource class you register; a custom provider does not make non-public handler methods or inherited generic bridges supported.
When both parameter binding and instance creation use the default providers, HTTP/SSE setup also emits RESOURCE_METHOD_UNANNOTATED_VALUE_PARAMETER for an unannotated parameter of a known scalar type (such as String, numeric primitives/wrappers, UUID, or date/time values), an enum, or a JDK collection/map type. These values are requested from InstanceProvider; they are not bound from request data without a binding annotation. Framework-injected and implicitly bound multipart parameters are exempt, as are application service classes and application-defined collection/map/number subclasses. A custom provider retains control of intentional injection.
This is a warning only: it neither rejects startup nor changes injection. It runs once for the discovered startup methods, with aliases deduplicated, rather than logging on each request; methods absent from that startup snapshot are not scanned.
Should you need more flexibility, here's how to supply your own InstanceProvider:
SokletConfig config = SokletConfig.withHttpServer(
HttpServer.fromPort(8080)
).instanceProvider(new InstanceProvider() {
@NonNull
@Override
public <T> T provide(@NonNull Class<T> instanceClass) {
// Use vanilla JDK reflection and create a new instance every time.
// More advanced implementations might cache off instances,
// specially instantiate certain types, etc.
try {
return instanceClass.getDeclaredConstructor().newInstance();
} catch (Exception e) {
throw new RuntimeException(e);
}
}
// Provides instances for a Resource Method parameters
@NonNull
@Override
@SuppressWarnings("unchecked")
public <T> T provide(@NonNull Parameter parameter) {
// Just delegate to provide(Class<T>) above
Class<T> instanceClass = (Class<T>) parameter.getType();
return provide(instanceClass);
}
}).build();
SokletConfig config = SokletConfig.withHttpServer(
HttpServer.fromPort(8080)
).instanceProvider(new InstanceProvider() {
@NonNull
@Override
public <T> T provide(@NonNull Class<T> instanceClass) {
// Use vanilla JDK reflection and create a new instance every time.
// More advanced implementations might cache off instances,
// specially instantiate certain types, etc.
try {
return instanceClass.getDeclaredConstructor().newInstance();
} catch (Exception e) {
throw new RuntimeException(e);
}
}
// Provides instances for a Resource Method parameters
@NonNull
@Override
@SuppressWarnings("unchecked")
public <T> T provide(@NonNull Parameter parameter) {
// Just delegate to provide(Class<T>) above
Class<T> instanceClass = (Class<T>) parameter.getType();
return provide(instanceClass);
}
}).build();
References:
Solving the "Robot Legs" Problem
It can be useful to configure your InstanceProvider to know the difference between "flavors" of the same type.
This is useful for solving the Robot Legs Problem, where you might examine a qualifying annotation on a parameter to disambiguate vended instances.
For example, given this Resource Method that accepts 2 LegFactory instances...
// Define some custom annotations...
@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface Left {}
@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface Right {}
// ...and use them in this Resource Method:
@GET("/robot-generator")
public Robot robotGenerator(
@Left LegFactory leftLegFactory,
@Right LegFactory rightLegFactory,
BodyFactory bodyFactory
) {
// Build a robot
LeftLeg leftLeg = leftLegFactory.buildLeg();
RightLeg rightLeg = rightLegFactory.buildLeg();
Body body = bodyFactory.build();
return new Robot(leftLeg, rightLeg, body);
}
// Define some custom annotations...
@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface Left {}
@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface Right {}
// ...and use them in this Resource Method:
@GET("/robot-generator")
public Robot robotGenerator(
@Left LegFactory leftLegFactory,
@Right LegFactory rightLegFactory,
BodyFactory bodyFactory
) {
// Build a robot
LeftLeg leftLeg = leftLegFactory.buildLeg();
RightLeg rightLeg = rightLegFactory.buildLeg();
Body body = bodyFactory.build();
return new Robot(leftLeg, rightLeg, body);
}
...your InstanceProvider::provide(Parameter) implementation might look like this:
@NonNull
@Override
@SuppressWarnings("unchecked")
public <T> T provide(@NonNull Parameter parameter) {
Class<T> type = (Class<T>) parameter.getType();
// Pick the appropriate LegFactory by inspecting annotations
if (type == LegFactory.class) {
if (parameter.isAnnotationPresent(Left.class))
return (T) LEFT_INSTANCE;
if (parameter.isAnnotationPresent(Right.class))
return (T) RIGHT_INSTANCE;
throw new IllegalArgumentException("LegFactory requires @Left or @Right");
}
// No qualifier logic needed - use the class-based path
return provide(type);
}
@NonNull
@Override
@SuppressWarnings("unchecked")
public <T> T provide(@NonNull Parameter parameter) {
Class<T> type = (Class<T>) parameter.getType();
// Pick the appropriate LegFactory by inspecting annotations
if (type == LegFactory.class) {
if (parameter.isAnnotationPresent(Left.class))
return (T) LEFT_INSTANCE;
if (parameter.isAnnotationPresent(Right.class))
return (T) RIGHT_INSTANCE;
throw new IllegalArgumentException("LegFactory requires @Left or @Right");
}
// No qualifier logic needed - use the class-based path
return provide(type);
}
Dependency Injection
In practice, you will likely want to tie in to whatever Dependency Injection library your application uses and have the DI infrastructure vend your instances.
Here's how it might look if you use Google Guice:
// Standard Guice setup
Injector injector = Guice.createInjector(new MyExampleAppModule());
SokletConfig config = SokletConfig.withHttpServer(
HttpServer.fromPort(8080)
).instanceProvider(new InstanceProvider() {
@NonNull
@Override
public <T> T provide(@NonNull Class<T> instanceClass) {
// Have Soklet ask the Guice Injector for the instance
return injector.getInstance(instanceClass);
}
}).build();
// Standard Guice setup
Injector injector = Guice.createInjector(new MyExampleAppModule());
SokletConfig config = SokletConfig.withHttpServer(
HttpServer.fromPort(8080)
).instanceProvider(new InstanceProvider() {
@NonNull
@Override
public <T> T provide(@NonNull Class<T> instanceClass) {
// Have Soklet ask the Guice Injector for the instance
return injector.getInstance(instanceClass);
}
}).build();
Now, your Resources are dependency-injected just like the rest of your application is:
public class WidgetResource {
private WidgetService widgetService;
// JSR 330 @Inject annotation used by Guice
@Inject
public WidgetResource(WidgetService widgetService) {
this.widgetService = widgetService;
}
@GET("/widgets")
public List<Widget> widgets() {
return widgetService.findWidgets();
}
}
public class WidgetResource {
private WidgetService widgetService;
// JSR 330 @Inject annotation used by Guice
@Inject
public WidgetResource(WidgetService widgetService) {
this.widgetService = widgetService;
}
@GET("/widgets")
public List<Widget> widgets() {
return widgetService.findWidgets();
}
}
Default Injections
The following injections do not consult your InstanceProvider because Soklet supports them out-of-the-box.
Soklet will automatically inject Resource Method Parameters which are decorated with the following annotations:
@QueryParameter(via Value Conversions)@PathParameter(via Value Conversions)@RequestCookie(via Value Conversions)@RequestHeader(via Value Conversions)@FormParameter(via Value Conversions)@Multipart(via Value Conversions)@RequestBody(via Value Conversions or yourRequestBodyMarshalerif configured)
Soklet will automatically inject Resource Method Parameters if they are of the following types:
Request(the current request)ResourceMethod(this Resource Method)InstanceProvider(viaSokletConfig)RequestBodyMarshaler(viaSokletConfig)ResponseMarshaler(viaSokletConfig)ValueConverterRegistry(viaSokletConfig)ResourceMethodResolver(viaSokletConfig)RequestInterceptor(viaSokletConfig)LifecycleObserver(viaSokletConfig)CorsAuthorizer(viaSokletConfig)ResourceMethodParameterProvider(viaSokletConfig)MetricsCollector(viaSokletConfig)SseServer(viaSokletConfig)
Instances any other type of parameter will be requested from your InstanceProvider.

