getCards() \{
return cards; // just returns the field
}Copy
Copy
Use 3 — validate, and make the model refuse to exist.
This one surprises people. If @PostConstruct throws an exception, adaptTo returns null.
So you can use it as a gate:
@PostConstruct
protected void init() throws IllegalStateException \{
if (StringUtils.isBlank(rootPath)) \{
throw new IllegalStateException("rootPath is required");
}
// ...
}Copy
Copy
Now a misconfigured component gives you null rather than a half-built model. Whether that is a good idea depends — usually returning a valid model with an isReady() flag is friendlier for HTL. But knowing the behaviour exists is worth a mark.
The rules:
The method must return void and take no arguments.
Make it protected or private — it is not part of your public API.
Name it whatever you like; init is conventional.
In an inheritance chain, the parent's @PostConstruct runs first.
The interview answer:
"Because injection happens after the object is constructed. Sling creates the instance first — so inside the constructor every injected field is still null — then injects the values, and only then calls @PostConstruct. So it's effectively the constructor that runs at the right time, once the injected values are actually available.
I use it for three things. Deriving values from injected fields, which can't be done in a constructor. Doing expensive work exactly once — that's the important one, because HTL can call a getter many times, and a getter inside a data-sly-list over fifty items runs fifty times. So I build lists and do lookups in @PostConstruct and store the result in a field.
And third, validation — if @PostConstruct throws, adaptTo returns null, so you can make a misconfigured model refuse to exist. Though in practice I usually prefer returning a valid model with an isReady() flag, because it gives HTL something cleaner to test against.
The method has to be void with no arguments, and I keep it protected since it isn't public API."
2.8 @OSGiService — calling a service from a model (syllabus point 10)
Your syllabus asks: "which annotation is used to call a service class in a model?"
The answer is @OSGiService.
@Model(adaptables = Resource.class)
public class ProductModel \{
```
@OSGiService
private ProductDataService productDataService;
@PostConstruct
protected void init() {
this.specs = productDataService.getSpecifications(productId);
}
```
}Copy
Copy
And now the follow-up that always comes: "why not @Reference?"
This is a good question and the answer shows whether you understand OSGi.
"@Reference is an OSGi Declarative Services annotation, and it only works inside an OSGi component — a class annotated with @Component. Those are created and managed by the DS runtime, which is what wires the references.
A Sling Model isn't an OSGi component. It's created by the Sling Models framework, freshly, each time something adapts to it. The DS runtime never sees it, so it can't inject anything into it.
So the rule is: @Reference inside an @Component, @OSGiService inside a @Model. Same idea — get me a service — but two different frameworks doing the injecting."
That distinction is exactly your syllabus points 10 and 11 side by side, and here they are as a table:
Inside a Sling Model Inside an OSGi component
Annotation @OSGiService @Reference
Framework doing the injecting Sling Models OSGi Declarative Services
Applies to classes marked @Model @Component
Examples Component models Services, servlets, filters, schedulers
Picking a specific implementation. If several implementations of an interface are registered, narrow it with a filter:
@OSGiService(filter = "(component.name=com.energy.core.services.impl.CachedProductDataService)")
private ProductDataService productDataService;Copy
Copy
One important caution. Injecting a service into a model is easy, which makes it easy to abuse. A model that calls an external API synchronously during rendering blocks the page. Keep the service call cheap, or move the fetch client-side — the caching argument from file 02 applies directly.
2.9 @ChildResource — reading child nodes (syllabus point 12)
Your syllabus asks why we use it. The answer is easiest as a contrast:
@ValueMapValue reads a property on this node. @ChildResource reads a child node of it.
Recall the composite multifield from file 02:
faqs/
├── item0/
│ ├── question = "What is a transformer in electricity?"
│ └── answer = "It changes the voltage level...
"
└── item1/
├── question = "What do electrical transformers do?"
└── answer = "They transfer energy between circuits...
"Copy
Copy
question and answer are not properties on the component node. They are properties on child nodes. @ValueMapValue cannot see them.
Three ways to use @ChildResource:
As a raw Resource:
@ChildResource
private Resource image; // the child node called "image"Copy
Copy
Adapted into another model — much more useful:
@ChildResource
private LinkModel link; // child node "link", adapted to LinkModelCopy
Copy
As a list — this is the multifield case:
@ChildResource
private List faqs; // faqs/item0, faqs/item1, ... each adaptedCopy
Copy
That last form is why the annotation matters in practice. A composite multifield produces child nodes, and @ChildResource with a List is how you read them. Section 8 has the full working example.
The interview answer:
"@ValueMapValue reads a property on the current node; @ChildResource reads a child node. The main reason I use it is composite multifields — those store each row as a child node like faqs/item0 rather than as properties on the component, so @ValueMapValue can't see them at all. I inject List with @ChildResource and Sling adapts each child node into that nested model class.
It's also useful for any structured sub-node — a nested configuration block, or an image node with several properties that deserves its own small model rather than five loose fields on the parent."
2.10 defaultInjectionStrategy — OPTIONAL versus REQUIRED
A small setting with large consequences.
@Model(
adaptables = Resource.class,
defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL
)Copy
Copy
REQUIRED is the default if you say nothing. It means: if any injection fails to find a value, the whole model fails and adaptTo returns null.
OPTIONAL means: a missing value is just null, and the model is still created.
For components, OPTIONAL is almost always right, because authors leave fields empty constantly. With REQUIRED, one blank optional field makes the entire component vanish.
But state the trade-off, because interviewers ask:
"OPTIONAL hides mistakes. If I typo a property name, I get null instead of an error — the model builds fine and the value is silently missing. So OPTIONAL is right for component models, since authors leave fields blank all the time and I'd rather render partially than not at all, but it does mean a typo shows up as an empty page rather than a stack trace. That's why 'my model is returning null' is such a common debugging question — and also why @Required on genuinely mandatory fields is worth using."
Per-field override:
@ValueMapValue(injectionStrategy = InjectionStrategy.REQUIRED)
private String rootPath; // this one really is mandatoryCopy
Copy
2.11 Interfaces, adapters and resourceType — the professional pattern
Worth knowing, because it is how Core Components are built and it comes up in senior rounds.
Instead of one class, you write an interface (the public contract) and an implementation (internal):
// Exported package -- this is the API
public interface Cta \{
String getLinkText();
String getLinkUrl();
}Copy
Copy
// NON-exported .impl package
@Model(
adaptables = Resource.class,
adapters = Cta.class, // register AS the interface
resourceType = "energy/components/cta", // bind to a resource type
defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL
)
public class CtaImpl implements Cta \{
// ...
}Copy
Copy
Now HTL uses the interface:
Copy
Copy
Why bother? Three reasons:
One — you can change the implementation without touching HTL or anything else that depends on the interface.
Two — resourceType binding. With it set, Sling can pick the right model based on the resource's type. That matters when several implementations share one interface, and it is required for the Sling Model Exporter (file 17).
Three — module boundaries. The interface lives in an exported package; the implementation lives in an .impl package that is not exported. That is proper OSGi hygiene, from file 01.
3. Internal Working
3.1 The full lifecycle of a model
sequenceDiagram
participant H as HTL
participant S as Sling Models framework
participant I as Injectors
participant M as Your model instance
H->>S: data-sly-use.cta="com.energy...CtaModel"
S->>S: is this class registered? (package scanned?)
S->>S: does it declare this adaptable type?
S->>M: create the instance (CONSTRUCTOR — fields null)
S->>I: for each annotated field, ask the right injector
I->>M: set linkText
I->>M: set linkUrl
I->>M: set style
S->>S: any REQUIRED injection fail?
S->>M: call @PostConstruct
M->>M: derive values, build lists ONCE
S-->>H: the ready model
H->>M: $\{cta.linkText} → calls getLinkText()
⛶ Fullscreen
Four points to draw out of that:
Registration is checked first. If the package is not scanned, nothing else happens — you get null immediately.
The constructor runs before injection. That is @PostConstruct's entire reason for existing.
A failed REQUIRED injection kills the whole model, returning null.
Getters are called last, and possibly many times. That is why expensive work belongs in @PostConstruct.
3.2 Why a model returns null — the five causes
"My Sling Model is null" is one of the most common AEM debugging questions. There are exactly five reasons, and knowing them in order is the answer:
graph TD
A\["adaptTo returned null"] --> B\{"Is the model registered?
/system/console/status-adapters"}
B -->|No| C\["1. PACKAGE NOT SCANNED
Sling-Model-Packages header"]
B -->|Yes| D\{"Does adaptables match
what you adapted from?"}
D -->|No| E\["2. WRONG ADAPTABLE
e.g. adapting a request to a
Resource-only model"]
D -->|Yes| F\{"Any REQUIRED injection
that found nothing?"}
F -->|Yes| G\["3. REQUIRED INJECTION FAILED
use OPTIONAL, or fix the property"]
F -->|No| H\{"Did @PostConstruct throw?"}
H -->|Yes| I\["4. POSTCONSTRUCT THREW
check error.log"]
H -->|No| J\["5. RESOURCE TYPE MISMATCH
if the model is resourceType-bound"]
⛶ Fullscreen
Being able to list those five in order is a genuinely strong answer, because it turns a vague symptom into a checklist.
3.3 Injector ranking — why @Inject is risky
Sling's injectors are tried in a defined order. Roughly:
1. script-bindings ← currentPage, currentStyle, wcmmode, pageManager
2. value-map ← node properties
3. child-resources ← child nodes
4. request-attributes
5. osgi-services
6. resource-path
7. self
8. sling-objectCopy
Copy
Notice that script bindings come first. That is why @Inject private String currentPage; gets you the HTL binding rather than a property of that name — the bindings injector answers before the ValueMap ever gets asked.
Injector-specific annotations skip this entire list and go directly to one injector. That is the whole argument for using them.
3.4 @Model(cache = true)
By default, adapting the same resource twice creates two separate instances, and any @PostConstruct work runs twice.
@Model(adaptables = Resource.class, cache = true)Copy
Copy
With caching on, the instance is reused for the same adaptable within the same request.
When it helps: a model doing genuinely expensive work in @PostConstruct that gets adapted from more than one place during a render.
When to leave it off: simple models. The caching has its own small cost, and for a model that just reads three properties it is not worth it.
4 sections hidden in Learn mode
4\. Important Interview Questions · 5. Cross Questions — how this topic gets drilled · 6. Best Interview Answers · 7. Real Project Examples
Show
8\. Coding Examples
Building on the components from file 02, at the three levels.
8.1 Simple — the CTA model, annotated line by line
package com.energy.core.models;
import org.apache.commons.lang3.StringUtils;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ResourceResolver;
import org.apache.sling.models.annotations.DefaultInjectionStrategy;
import org.apache.sling.models.annotations.Model;
import org.apache.sling.models.annotations.injectorspecific.SlingObject;
import org.apache.sling.models.annotations.injectorspecific.ValueMapValue;
import javax.annotation.PostConstruct;
@Model(
// Only needs CONTENT, so Resource is enough.
// Easier to test, and reusable from a servlet or scheduler.
adaptables = Resource.class,
```
// Authors leave fields blank constantly. With REQUIRED (the
// default), one empty optional field would make the whole
// model null and the component would vanish.
defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL
```
)
public class CtaModel \{
```
// Injector-SPECIFIC. Goes straight to the ValueMap.
// Field name = property name.
@ValueMapValue
private String linkText;
@ValueMapValue
private String linkUrl;
@ValueMapValue
private String style;
// Boolean (not boolean): a missing property gives null, which we
// can distinguish from an author explicitly setting false.
// This is the uncheckedValue situation from file 02.
@ValueMapValue
private Boolean newTab;
// @SlingObject gets us common Sling objects without a request
@SlingObject
private ResourceResolver resourceResolver;
// Derived fields -- NOT injected, computed in @PostConstruct
private String resolvedUrl;
private boolean openInNewTab;
/**
* Runs AFTER injection. In the constructor every field above
* would still be null, which is exactly why this hook exists.
*/
@PostConstruct
protected void init() {
this.resolvedUrl = resolveUrl(linkUrl);
this.openInNewTab = Boolean.TRUE.equals(newTab) || isDocument(linkUrl);
}
private String resolveUrl(String url) {
if (StringUtils.isBlank(url)) {
return null;
}
if (url.startsWith("/content")) {
String mapped = resourceResolver.map(url);
return url.startsWith("/content/dam") ? mapped : mapped + ".html";
}
return url;
}
private boolean isDocument(String url) {
return url != null && StringUtils.endsWithAny(
url.toLowerCase(), ".pdf", ".docx", ".xlsx");
}
// GETTERS -- HTL can only reach values through these.
// ${cta.linkText} calls getLinkText().
public String getLinkText() {
return StringUtils.defaultString(linkText); // never null
}
public String getLinkUrl() {
return resolvedUrl;
}
public String getStyle() {
return StringUtils.defaultIfBlank(style, "arrow");
}
/** Returning null means HTL omits the attribute entirely. */
public String getTarget() {
return openInNewTab ? "_blank" : null;
}
public String getRel() {
return openInNewTab ? "noopener noreferrer" : null;
}
public boolean isReady() {
return StringUtils.isNotBlank(linkText) && StringUtils.isNotBlank(resolvedUrl);
}
```
}Copy
Copy
The five decisions to be able to defend:
adaptables = Resource.class — content only, so keep the dependency small.
OPTIONAL — because authors leave fields blank, and a vanished component is worse than a partial one.
Boolean not boolean — so "not set" and "false" stay distinguishable.
@PostConstruct for the derived values — impossible in a constructor, and it runs once.
Getters never return null for text, so HTL never renders the literal string "null". The exception is getTarget() and getRel(), where null is deliberate — HTL omits the whole attribute rather than writing target="".
8.2 Medium — @ChildResource for a composite multifield
This is syllabus point 12 in practice, reading the FAQ accordion from file 02.
The nested row model — one per multifield row:
package com.energy.core.models;
import org.apache.commons.lang3.StringUtils;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.models.annotations.DefaultInjectionStrategy;
import org.apache.sling.models.annotations.Model;
import org.apache.sling.models.annotations.injectorspecific.SlingObject;
import org.apache.sling.models.annotations.injectorspecific.ValueMapValue;
@Model(
adaptables = Resource.class,
defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL
)
public class FaqItemModel \{
```
// These read properties on the CHILD node (faqs/item0),
// because that is the resource this model was adapted from.
@ValueMapValue
private String question;
@ValueMapValue
private String answer;
// The child node's OWN resource -- used for a stable unique id
@SlingObject
private Resource resource;
public String getQuestion() {
return StringUtils.defaultString(question);
}
public String getAnswer() {
return StringUtils.defaultString(answer);
}
/**
* IDs derived from the resource PATH, not a counter.
* A counter restarts at 0 for each accordion, so two accordions
* on one page would both emit id="faq-0" -- duplicate IDs break
* the aria-controls relationships and are invalid HTML.
*/
public String getId() {
return "faq-" + Math.abs(resource.getPath().hashCode());
}
public boolean isValid() {
return StringUtils.isNotBlank(question) && StringUtils.isNotBlank(answer);
}
```
}Copy
Copy
The parent model — this is where @ChildResource does its work:
package com.energy.core.models;
import org.apache.commons.lang3.StringUtils;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.models.annotations.DefaultInjectionStrategy;
import org.apache.sling.models.annotations.Model;
import org.apache.sling.models.annotations.injectorspecific.ChildResource;
import org.apache.sling.models.annotations.injectorspecific.ValueMapValue;
import javax.annotation.PostConstruct;
import java.util.Collections;
import java.util.List;
import java.util.stream.Collectors;
@Model(
adaptables = Resource.class,
defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL
)
public class FaqModel \{
```
// A PROPERTY on this node
@ValueMapValue
private String heading;
/**
* CHILD NODES of this node.
*
* A composite multifield stores each row as a child node:
* faqs/item0/question, faqs/item0/answer
* faqs/item1/question, faqs/item1/answer
*
* @ValueMapValue could never see these -- they are not properties
* on this node. @ChildResource reads them, and Sling adapts each
* child into FaqItemModel because that is the List's type.
*/
@ChildResource
private List faqs;
private List validFaqs;
@PostConstruct
protected void init() {
// Filter ONCE here, not in the getter -- HTL may call
// getFaqs() several times per render.
this.validFaqs = (faqs == null)
? Collections.emptyList()
: faqs.stream()
.filter(FaqItemModel::isValid)
.collect(Collectors.toList());
}
public String getHeading() {
return StringUtils.defaultString(heading);
}
/** Empty list, never null -- data-sly-list handles empty cleanly. */
public List getFaqs() {
return validFaqs;
}
public boolean isReady() {
return !validFaqs.isEmpty();
}
```
}Copy
Copy
The three points to make about this pair:
@ChildResource on a List reads the child nodes and adapts each one into the nested model. Sling works out the target type from the generic parameter.
The injected list can be null if the author never added a row. That is why @PostConstruct normalises it and the getter returns an empty list.
Filtering happens once in @PostConstruct, not in the getter — the same lesson as story 1.
8.3 Complex — request-adaptable, with a service and a policy
Everything together: @ScriptVariable needing the request, @OSGiService for syllabus point 10, and a hard ceiling.
package com.energy.core.models;
import com.day.cq.wcm.api.Page;
import com.day.cq.wcm.api.PageManager;
import com.day.cq.wcm.api.designer.Style;
import com.energy.core.services.ProductDataService;
import org.apache.commons.lang3.StringUtils;
import org.apache.sling.api.SlingHttpServletRequest;
import org.apache.sling.models.annotations.DefaultInjectionStrategy;
import org.apache.sling.models.annotations.Model;
import org.apache.sling.models.annotations.injectorspecific.OSGiService;
import org.apache.sling.models.annotations.injectorspecific.ScriptVariable;
import org.apache.sling.models.annotations.injectorspecific.ValueMapValue;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.annotation.PostConstruct;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
@Model(
// REQUEST-adaptable, because @ScriptVariable needs the HTL
// bindings, which only exist during a render.
adaptables = SlingHttpServletRequest.class,
defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL
)
public class CategoryListingModel \{
```
private static final Logger LOG =
LoggerFactory.getLogger(CategoryListingModel.class);
/** Hard ceiling. A misconfigured root should degrade, not kill the instance. */
private static final int MAX_ITEMS = 200;
// --- content: dialog properties ---
@ValueMapValue
private String rootPath;
@ValueMapValue
private Integer maxItems;
// --- request-only: HTL bindings ---
/** The page being rendered. Needs the request. */
@ScriptVariable
private Page currentPage;
/** The RESOLVED POLICY for this component on this template -- file 03. */
@ScriptVariable
private Style currentStyle;
@ScriptVariable
private PageManager pageManager;
// --- an OSGi service: SYLLABUS POINT 10 ---
/**
* @OSGiService, NOT @Reference.
*
* @Reference is an OSGi Declarative Services annotation and only
* works in classes DS manages -- i.e. @Component classes. A Sling
* Model is created by the Sling Models framework, so DS never
* sees it and cannot inject into it.
*/
@OSGiService
private ProductDataService productDataService;
private List cards;
private String effectiveRootPath;
@PostConstruct
protected void init() {
// Fall back to the current page if the author left it blank
this.effectiveRootPath = StringUtils.isNotBlank(rootPath)
? rootPath
: currentPage.getPath();
this.cards = collectCards();
}
private List collectCards() {
Page root = pageManager.getPage(effectiveRootPath);
if (root == null) {
LOG.warn("Listing root not found: {}", effectiveRootPath);
return Collections.emptyList();
}
// A bounded traversal under a KNOWN root needs no Oak index
// and has predictable cost. A repo-wide query would need one.
int limit = resolveLimit();
List result = new ArrayList<>();
Iterator children = root.listChildren();
while (children.hasNext() && result.size() < limit) {
Page child = children.next();
if (child.isHideInNav()) {
continue;
}
// adaptTo can ALWAYS return null -- guard it
CardModel card = child.getContentResource() != null
? child.getContentResource().adaptTo(CardModel.class)
: null;
if (card != null && card.isValid()) {
result.add(card);
}
}
return result;
}
private int resolveLimit() {
// Author value, else the POLICY default, else our constant
if (maxItems != null && maxItems > 0) {
return Math.min(maxItems, MAX_ITEMS);
}
int fromPolicy = currentStyle != null
? currentStyle.get("defaultMaxItems", 12)
: 12;
return Math.min(fromPolicy, MAX_ITEMS);
}
public List getCards() {
return cards;
}
public boolean isReady() {
return !cards.isEmpty();
}
```
}Copy
Copy
What to point at when walking an interviewer through this:
Why request-adaptable — @ScriptVariable for currentPage, currentStyle and pageManager. Without those three, this model would adapt from Resource and be easier to test.
@OSGiService not @Reference — with the reason, not just the fact.
A hard ceiling constant — an author typing a bad root path should produce an empty list, not a repository walk that takes the instance down.
Every adaptTo is null-checked, including inside the loop.
The limit falls back through three sources — author, then policy, then constant. That policy fallback is file 03 meeting file 05.
8.4 The interface pattern — how Core Components do it
// Exported package: the public contract
package com.energy.core.models;
public interface Cta \{
String getLinkText();
String getLinkUrl();
String getStyle();
boolean isReady();
}Copy
Copy
// NON-exported .impl package: the implementation
package com.energy.core.models.impl;
import com.energy.core.models.Cta;
// ...
@Model(
adaptables = Resource.class,
adapters = Cta.class, // register AS the interface
resourceType = CtaImpl.RESOURCE\_TYPE, // bind to a resource type
defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL
)
public class CtaImpl implements Cta \{
```
protected static final String RESOURCE_TYPE = "energy/components/cta";
// ... same fields and logic as 8.1
```
}Copy
Copy
HTL uses the interface:
Copy
Copy
Three benefits, worth stating: the implementation can change without touching HTL; the resourceType binding lets Sling pick the right implementation and is required by the Model Exporter; and the impl package stays unexported, which is proper OSGi module hygiene from file 01.
8.5 Unit test — testing what actually breaks
package com.energy.core.models;
import com.energy.core.services.ProductDataService;
import io.wcm.testing.mock.aem.junit5.AemContext;
import io.wcm.testing.mock.aem.junit5.AemContextExtension;
import org.apache.sling.api.resource.Resource;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.Mockito;
import static org.junit.jupiter.api.Assertions.\*;
@ExtendWith(AemContextExtension.class)
class FaqModelTest \{
```
private final AemContext context = new AemContext();
@BeforeEach
void setUp() {
context.load().json("/faq/content.json", "/content");
// Register BOTH the parent and the nested model, or
// @ChildResource cannot adapt the child nodes.
context.addModelsForClasses(FaqModel.class, FaqItemModel.class);
// Mock any injected OSGi service
context.registerService(ProductDataService.class,
Mockito.mock(ProductDataService.class));
}
@Test
void readsQuestionsFromChildNodes() {
FaqModel model = adapt("/content/faq");
assertEquals(2, model.getFaqs().size());
assertEquals("What is a transformer in electricity?",
model.getFaqs().get(0).getQuestion());
}
@Test
void returnsEmptyListWhenAuthorAddedNoRows() {
// The injected List is NULL here, not empty.
// This is the case @PostConstruct normalises.
FaqModel model = adapt("/content/faq-empty");
assertNotNull(model);
assertTrue(model.getFaqs().isEmpty(), "must be empty, never null");
assertFalse(model.isReady());
}
@Test
void skipsRowsWhereTheAnswerIsBlank() {
// Authors WILL do this. Most common real-world case.
FaqModel model = adapt("/content/faq-partial");
assertEquals(1, model.getFaqs().size());
}
@Test
void twoAccordionsOnOnePageProduceDifferentIds() {
String first = adapt("/content/page/faq-one").getFaqs().get(0).getId();
String second = adapt("/content/page/faq-two").getFaqs().get(0).getId();
assertNotEquals(first, second, "duplicate IDs break aria-controls");
}
private FaqModel adapt(String path) {
Resource resource = context.resourceResolver().getResource(path);
assertNotNull(resource, "test content missing at " + path);
FaqModel model = resource.adaptTo(FaqModel.class);
assertNotNull(model, "model failed to adapt at " + path);
return model;
}
```
}Copy
Copy
Two things to call out. You must register both model classes, or @ChildResource cannot adapt the children — that is a real and confusing test failure. And the tests target the cases authors actually create: no rows, a half-filled row, two instances on a page. Testing that a getter returns its field proves nothing.
9. Common Mistakes
The mistake What actually happens The fix
Package not registered for scanning Model silently returns null Sling-Model-Packages; check status-adapters
Wrong adaptables Silent null when adapting from the other type Declare what you actually adapt from
Leaving defaultInjectionStrategy as REQUIRED One blank field makes the whole component vanish OPTIONAL for component models
Using @Inject instead of injector-specific Ambiguous, slower, can pick up a script binding @ValueMapValue, @ChildResource, etc.
Doing work in a getter HTL calls it repeatedly — sometimes hundreds of times @PostConstruct, store in a field
Trying to initialise in the constructor Fields are still null there @PostConstruct
Returning null from a getter HTL renders "null", or you need guards everywhere Empty string / empty list
Not null-checking adaptTo NullPointerException, the classic AEM one Always guard, including inside loops
@Reference in a model Does not compile meaningfully / never injects @OSGiService
int instead of Integer Missing property becomes 0, indistinguishable from a real 0 Use the wrapper type
boolean where "not set" matters Missing property becomes false Boolean
@ValueMapValue for a child node Nothing injected — it only reads properties @ChildResource
Forgetting to register the nested model in tests @ChildResource list is empty, confusing failure addModelsForClasses(Parent.class, Child.class)
Request-adaptable when Resource would do Harder to test, unusable outside a render Default to Resource.class
Unbounded list building A bad path walks the whole repository A hard ceiling constant
Blocking external call in the model Slow pages, threads hang without a timeout OSGi service, timeouts, cache, or fetch client-side
Property name mismatch with no @Named Silent null under OPTIONAL @Named("jcr:title")
10. Best Practices
On adaptables. Default to Resource.class. Move to the request only when you genuinely need @ScriptVariable or request data — and notice when that is only one or two fields, because it may mean the model should be split.
On annotations. Always injector-specific. @Inject is legacy: it works, but it is ambiguous and occasionally picks up the wrong source.
On @PostConstruct. Derive there, build lists there, do lookups there. Keep getters trivial. Assume every getter can be called many times.
On null. Never return null from a getter — empty string for text, empty list for collections. Always null-check adaptTo, including inside loops. Use wrapper types where "not set" and "zero/false" mean different things.
On structure. One model per component, and split when a model grows past roughly a couple of hundred lines or starts serving several unrelated concerns. Interface plus non-exported .impl for anything reused or exported.
On safety. A hard ceiling on anything that builds a collection. Timeouts on anything that leaves the JVM. Log at warn when a configured path does not resolve, so a misconfiguration is visible rather than silent.
On testing. Test the empty case, the partial case and the two-instances-on-a-page case. Register nested models. Mock injected services with context.registerService.
11. Debugging Tips
The single most useful console: /system/console/status-adapters. If your model's adapter is not listed there, the class is not registered at all — a scanning problem, not a code problem. Checking this first saves a lot of time staring at annotations.
The five-cause checklist for a null model, in order:
Package not scanned → status-adapters
Wrong adaptable → does adaptables match what you called adaptTo on?
A REQUIRED injection failed → switch to OPTIONAL temporarily to see if it appears
@PostConstruct threw → error.log
Resource type mismatch → only if the model is resourceType-bound
A quick test from HTL. Output the model object itself:
$\{listing}Copy
Copy
An object reference means the model resolved and the problem is in a getter. Nothing at all means the adaptation returned null.
When a value is missing but the model resolves: the property name and the field name probably do not match, and OPTIONAL is hiding it. Open the node in CRXDE and compare the actual property name against your field. This is the same "split the problem in half" move from file 02 — is the data absent, or is the reading wrong?
When something is slow: add a temporary log line at the top of the suspect getter and count how often it appears for one page render. If it is more than once, the work belongs in @PostConstruct.
The Sling Log Tracer at /system/console/tracer lets you trace what happened during a single request without redeploying — useful when the problem only reproduces on a specific page.
Tool What it tells you
/system/console/status-adapters Whether the model is registered at all
/system/console/tracer What happened during one request
/system/console/bundles Whether the core bundle is even ACTIVE
error.log @PostConstruct exceptions
$\{model} in HTL Did the adaptation succeed
/crx/de The real property names on the node
12\. Performance Optimization
Expensive work goes in @PostConstruct. This is the biggest single lever, and story 1 shows why — a getter used three times in HTL, over a twenty-item list, ran two hundred times.
Prefer Resource adaptables. Cheaper to create and testable without a request.
Injector-specific annotations. @Inject may try several injectors per field. On a page with fifty component instances that adds up.
A hard ceiling on collections. Not just for correctness — an unbounded listChildren() under a misconfigured root can genuinely take an instance down.
Prefer a bounded traversal over a repository-wide query. Walking children of a known path needs no Oak index and has predictable cost. If you must query, it must be indexed and limited.
Never block on an external call during rendering without a timeout, and think hard about whether that data should be fetched client-side instead so the page stays dispatcher-cacheable.
cache = true when the same model is adapted from several places in one render and does real work. Not worth it for a model reading three properties.
2 sections hidden in Learn mode
13\. Real Production Scenarios · 14. Follow-up Questions
Show
15\. Comparison Tables
Resource.class vs SlingHttpServletRequest.class
Resource.class SlingHttpServletRequest.class
Gives access to Content only Content plus request context
@ValueMapValue Yes Yes (via the request's resource)
@ChildResource Yes Yes
@ScriptVariable No Yes
Selectors, suffix, parameters No Yes
Unit testing Easier More setup
Usable from a scheduler or servlet Yes No
Use as The default Only when you need request data
@Inject vs injector-specific
@Inject @ValueMapValue etc.
Source Tries every injector in ranking order One specific injector
Self-documenting No Yes
Performance Slower Faster
Risk Can pick up a script binding None
Status Legacy but functional Preferred
@ValueMapValue vs @ChildResource
@ValueMapValue @ChildResource
Reads A property on this node A child node
Types String, Boolean, Integer, arrays, Calendar Resource, a model, or a List of models
Use for Dialog fields Composite multifields, nested structures
@OSGiService vs @Reference — syllabus points 10 and 11
@OSGiService @Reference
Used inside A Sling Model An OSGi @Component
Injected by Sling Models framework OSGi Declarative Services
Works in a model Yes No
Works in a servlet or service No Yes
Filtering filter = "(...)" target = "(...)"
REQUIRED vs OPTIONAL
REQUIRED (default) OPTIONAL
Missing value Whole model → null That field → null
Good for Genuinely mandatory config Component models
Downside One blank field kills the component Hides typos
Sling Model vs WCMUsePojo vs scriptlet
Scriptlet WCMUsePojo Sling Model
Where the logic lives In the view A class extending an AEM base class A plain annotated class
Unit testable No Awkward Yes
Base class required — Yes No
Model Exporter / headless No No Yes
Status Dead Legacy Current