Skip to main content

Kernel Services

The Sakai Kernel provides essential services that are used throughout the platform. These services handle core functionality like user management, authorization, content hosting, and event tracking.
All tools should use kernel services for core functionality rather than implementing their own user management, authorization, or content storage systems.

What is the Kernel?

The Kernel contains the basic services that are used throughout Sakai. It provides:
  • API layer: Service interfaces defining contracts
  • Implementation layer: Concrete implementations of services
  • Component Manager: Spring-based service wiring and lifecycle management
  • Utility classes: Common utilities like FormattedText
Reference: kernel/README.md:1-53

Core Kernel Services

User Management Services

UserDirectoryService

Manages end-user modeling for Sakai including user creation, lookup, and authentication.
package org.sakaiproject.user.api;

public interface UserDirectoryService extends EntityProducer {
    /** Reference root for user resources */
    static final String REFERENCE_ROOT = "/user";
    
    /** Admin user ID */
    static final String ADMIN_ID = "admin";
    
    // Security permissions
    static final String SECURE_ADD_USER = "user.add";
    static final String SECURE_REMOVE_USER = "user.del";
    static final String SECURE_UPDATE_USER_ANY = "user.upd.any";
    static final String SECURE_UPDATE_USER_OWN = "user.upd.own";
}
Reference: kernel/api/src/main/java/org/sakaiproject/user/api/UserDirectoryService.java:32-80

Authorization Services

AuthzGroupService

Manages authorization groups (realms) and checks if users are allowed to perform specific functions in a context.
package org.sakaiproject.authz.api;

public interface AuthzGroupService extends EntityProducer {
    /** Reference root for authz resources */
    static final String REFERENCE_ROOT = "/realm";
    
    /** Standard role names */
    static final String ANON_ROLE = ".anon";  // Anonymous role
    static final String AUTH_ROLE = ".auth";  // Authenticated role
    
    /** Security permissions */
    static final String SECURE_ADD_AUTHZ_GROUP = "realm.add";
    static final String SECURE_UPDATE_AUTHZ_GROUP = "realm.upd";
    static final String SECURE_REMOVE_AUTHZ_GROUP = "realm.del";
}
The AuthzGroupService doesn’t automatically validate that user IDs are still valid. If you need to ensure a user exists, check with UserDirectoryService.
Reference: kernel/api/src/main/java/org/sakaiproject/authz/api/AuthzGroupService.java:33-80

Site Management Services

SiteService

Manages Sakai sites (workspaces, course sites, project sites).
package org.sakaiproject.site.api;

public interface SiteService extends EntityProducer {
    /** Application ID */
    static final String APPLICATION_ID = "sakai:site";
    
    /** Entity reference subtypes */
    static final String SITE_SUBTYPE = "site";
    static final String GROUP_SUBTYPE = "group";
    static final String PAGE_SUBTYPE = "page";
    static final String TOOL_SUBTYPE = "tool";
    
    /** Event names */
    static final String SITE_VISIT = "site.visit";
    static final String SECURE_ADD_SITE = "site.add";
    static final String SECURE_ADD_COURSE_SITE = "site.add.course";
    static final String SECURE_REMOVE_SITE = "site.del";
}
Reference: kernel/api/src/main/java/org/sakaiproject/site/api/SiteService.java:42-100

Content Management Services

ContentHostingService

Manages shared content resources and collections, based on WebDAV terminology.
package org.sakaiproject.content.api;

/**
 * ContentHostingService manages resources (files) and collections (folders).
 * Resources have:
 * - Resource ID (URI)
 * - Media type (MIME type like image/gif, text/html)
 * - Properties (name-value pairs)
 * - Content (file data)
 */
public interface ContentHostingService extends EntityProducer {
    // Resource management methods
    // Collection management methods
    // Property management methods
}
Key Concepts:
  • Resource: A file with media type, ID, and properties
  • Collection: A folder containing resources (also a resource itself)
  • Properties: WebDAV-style name-value pairs (“live” generated by system, “dead” user-maintained)
Reference: kernel/api/src/main/java/org/sakaiproject/content/api/ContentHostingService.java:56-80

Event Tracking Services

EventTrackingService

Provides activity event tracking and monitoring throughout Sakai.
package org.sakaiproject.event.api;

/**
 * The event tracking service provides:
 * - Event posting by generators
 * - Event monitoring and notification
 * - Event archival storage
 */
public interface EventTrackingService {
    static final String UNKNOWN_USER = "?";
    
    /**
     * Construct an Event object.
     * 
     * @param event The Event id
     * @param resource The resource reference
     * @param modify true if event caused modification, false for access
     * @return A new Event object
     */
    Event newEvent(String event, String resource, boolean modify);
}
Reference: kernel/api/src/main/java/org/sakaiproject/event/api/EventTrackingService.java:30-80

Complete List of Kernel Services

The kernel provides implementations for these core services:
ServicePackagePurpose
Aliasorg.sakaiproject.aliasManage resource aliases
Antivirusorg.sakaiproject.antivirusVirus scanning for uploads
Authzorg.sakaiproject.authzAuthorization and permissions
Clusterorg.sakaiproject.clusterCluster management
Componentorg.sakaiproject.componentComponent/service wiring
Conditionsorg.sakaiproject.conditionsConditional release
ConfigStoreorg.sakaiproject.configConfiguration storage
Contentorg.sakaiproject.contentContent hosting (files)
DBorg.sakaiproject.dbDatabase access
Emailorg.sakaiproject.emailEmail sending
Entityorg.sakaiproject.entityEntity management
Eventorg.sakaiproject.eventEvent tracking
Memoryorg.sakaiproject.memoryCaching services
MessageBundleorg.sakaiproject.messagebundlei18n message bundles
Messagingorg.sakaiproject.messagingMessaging/notifications
Siteorg.sakaiproject.siteSite management
Tasksorg.sakaiproject.tasksTask management
Timeorg.sakaiproject.timeTime/date utilities
Toolorg.sakaiproject.toolTool registration
Userorg.sakaiproject.userUser management
Reference: kernel/README.md:12-33

Service Implementation Pattern

Each kernel service follows this structure:
kernel/
├── api/
│   └── src/main/java/org/sakaiproject/{service}/api/
│       ├── {Service}Service.java        # Service interface
│       └── {Service}.java               # Domain objects
├── kernel-impl/
│   └── src/main/java/org/sakaiproject/{service}/impl/
│       └── {Service}ServiceImpl.java    # Implementation
│   └── src/main/webapp/WEB-INF/
│       └── {service}-components.xml     # Spring wiring

Example: Site Service Wiring

<!-- site-components.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans">
    
    <bean id="org.sakaiproject.site.api.SiteService"
          class="org.sakaiproject.site.impl.SiteServiceImpl"
          init-method="init"
          destroy-method="destroy">
        
        <!-- Inject dependencies -->
        <property name="sqlService" 
                  ref="org.sakaiproject.db.api.SqlService"/>
        <property name="entityManager" 
                  ref="org.sakaiproject.entity.api.EntityManager"/>
        <property name="authzGroupService" 
                  ref="org.sakaiproject.authz.api.AuthzGroupService"/>
    </bean>
    
</beans>

Utility Classes

The kernel also provides common utility classes:

FormattedText

One of the most commonly used utilities for processing and sanitizing HTML:
FormattedText formattedText = ComponentManager.get(FormattedText.class);

// Convert plain text to HTML
String html = formattedText.convertPlaintextToFormattedText(plainText);

// Process and sanitize HTML
String clean = formattedText.processFormattedText(dirtyHtml, new StringBuilder());

// Escape HTML
String escaped = formattedText.escapeHtml(text, true);
Reference: kernel/README.md:42

Best Practices

Use Kernel Services

Always use kernel services for user management, authorization, content storage, and email rather than implementing your own.

Service Location

Access services via ComponentManager.get() rather than direct instantiation.

Transaction Management

Use Spring transaction management for database operations.

Event Posting

Post events for significant user actions to enable analytics and integration.
New core services should be added to the kernel, not to individual tools. If you’re implementing functionality that multiple tools need, consider creating a new kernel service.

Next Steps

Tool Architecture

Learn how to build tools using kernel services

Sites & Workspaces

Understand sites, pages, and tool placement

Build docs developers (and LLMs) love