Skip to end of metadata
Go to start of metadata


This contains information related to the Entity Broker system (a.k.a. entity 2.0) in Sakai. Ideally we want flexible entities which make development of integrated Sakai tools easier and more flexible. Our goals are to make the entity system easier on developers (easier to use and understand) and more powerful (easier to extend and improve).
In the EB system the concept of an entity is very flexible. It can be a POJO, persistent object, string, or really anything you like. Entities do not have to be backed by database data or even real data at all. Each entity type (as defined by a unique prefix) has a set of capabilities associated with it. These are fine-grained and defined by the developer who writes the EntityProvider for that entity type. An EntityProvider can reside in a Sakai component or a webapp and can implement as few as one interface with one method or as many methods as the developer desires.
The Entity Broker seamlessly integrates with the existing Entity system in Sakai (EntityProducer and Entity) and entities created using entity providers are accessible in Sakai as if they were created using the legacy system.

In the Entity Broker system we refer to entities using globally unique but well-known references constructed from ids and prefixes.
prefix = globally unique identifier for an entity type (e.g. blog-entry, eval-template)
id = locally unique identifier for an entity of a type (e.g. 1, "one")
reference = globally unique identifier (or reference) to an entity (e.g. /prefix/id, /eval-item/5)
space = a way to refer to an entity type (e.g. blog-entry, eval-template) (e.g. /prefix)


  • Support technology, tool, and entity interoperability using conventions and references without hard dependencies
  • Make it easier for developers to work with and integrate their tools with Sakai
  • Provide for easier support for RESTful URLs and clean URL spaces


Usage with presentation frameworks (for URLs)


  • Capabilities are extensions to the the entity provider and broker system. They allow the entity system to be easily extended in a way which does not create interlocking dependencies and even allows multiple projects to implement capabilities for the same entity set.
    Capabilites can be created by anyone and should be located within the relevant project, though there are some capabilities that are within the entity broker project.

Development Status

  • In core Sakai release
  • TODO
    • Add support for custom actions (via REST) (tick)
    • Add support for URL redirects (tick)
    • Move to kernel
    • Add support for archiving entities
    • Add support for searching entities


  • Entity Broker trunk code (in Sakai trunk):
    • The versions included with 2.7 and later releases are up to date, see instructions below if you need to update for security patches
  • Installation is the same as for other sakai add-ons and tools
    • Check for older versions of the entitybroker jars in your TOMCAT_HOME/shared/lib and remove any you find
    • Run mvn clean install sakai:deploy from inside the entitybroker svn checkout root

Entity Broker Design

  • Take a look here if you are interested in the concepts behind entities or the way things link together


  1. I am relatively new to Sakai, and so I am trying not to use the Entity API. But I am completely missing how one should use Entity Broker with a resource. If I have resources in the content repository, and I get them say from the content hosting service as follows (snippet from the ContentViewer contrib module)

    ContentCollection cc = contentHostingService.getCollection(folderpath);

    I can use the ContentCollection methods, etc, but those eventually boil down to Entity API methods when I eventually get an entity out of the collection. So where does the new Entity Broker stuff fit in? Or does it? Is Entity Broker et al only for new stuff?


    1. In general you will still need to use the actual CHS APIs to traverse collections and do things which are specific to an entity type. That said, you can use the EB to generate URLs to resources or to retrieve a resource object but for more complex things you would always need to move on to the service. This is by design and there is no reason to attempt to supercede the service for complex operations.