| Version 3

Spring Data Sophora Getting Started

This part of the reference documentation will guide you through the integration of the Spring Data Sophora library into your Java project.

Archived documentation for Sophora 3. End-of-support date for this version: 7/25/21

Documentation for Sophora 4

This part of the reference documentation will guide you through the integration of the Spring Data Sophora library into your Java project.

Maven Dependency

In order to use Spring Data Sophora you have to add the following Maven dependency to your project:



In order to access a Sophora repository (i.e. a content of a Sophora Server) you will have to declare an interface that inherits from SophoraDocumentRepository. This interface will provide models of a specific type. Example:

package com.example.sophora.sds.repository;

import com.example.sophora.sds.model.MyStory;
import com.subshell.sophora.spring.data.repository.SophoraDocumentRepository;

public interface MyStoryRepository extends SophoraDocumentRepository<MyStory> {

The repository (and models) needs to be scanned by Spring Data Sophora to get initialized and registered properly. This can be done by registering the package of the repository with @EnableSophoraRepositories:

package com.example.sophora.sds;

import org.springframework.context.annotation.Configuration;

import com.subshell.sophora.spring.data.repository.config.EnableSophoraRepositories;

@EnableSophoraRepositories(basePackages = {"com.example.sophora.sds"})		// list here your packages to scan for repositories and models
public class SdsSpringConfiguration {


The following example is a Java Model for all documents of the fictional node type sophora-example-nt:story for which we can use the above repository.

package com.example.sophora.sds.model;

import com.subshell.sophora.spring.data.annotations.NodeType;
import com.subshell.sophora.spring.data.annotations.PropertyNamespace;
import com.subshell.sophora.spring.data.repository.entities.SophoraDocumentEntity;

import lombok.Data;
import lombok.EqualsAndHashCode;

@NodeType(value = "sophora-example-nt:story")
@EqualsAndHashCode(callSuper = true)
public class MyStory extends SophoraDocumentEntity {

    private String title;
    private String teaser;


This Java class will be used to instantiate Java objects for all documents with the node type sophora-example-nt:story. The objects will have a title and a teaser field which refer to their appropriate properties within the Sophora document. If you want to learn more about writing Spring Data Sophora models, please visit the corresponding part of the documentation.

REST Controller

The above Java model can now be used to deliver content of a story document. E.g. within a REST controller:

package com.example.sophora.web;

import com.example.sophora.sds.model.MyStory;
import com.example.sophora.sds.repository.MyStoryRepository;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import java.util.Optional;
import lombok.RequiredArgsConstructor;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;

public class MyStoryController {

    private final MyStoryRepository repository;

    public String bySophoraId(@PathVariable("sophoraId") String sophoraId) throws JsonProcessingException {
        Optional<MyStory> storyOpt = repository.findBySophoraId(sophoraId);
        if (storyOpt.isEmpty()) {
            throw new ResponseStatusException(HttpStatus.NOT_FOUND,
                "Unable to find document with Sophora ID " + sophoraId);

        MyStory story = storyOpt.get();
        ObjectMapper mapper = new ObjectMapper();
        ObjectNode storyJson = mapper.createObjectNode();
        storyJson.put("sophoraId", story.getSophoraId());
        storyJson.put("title", story.getTitle());
        storyJson.put("teaser", story.getTeaser());

        return mapper.writerWithDefaultPrettyPrinter()


Last modified on 8/5/21

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.