or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

http-services.mdindex.mdsystem-services.mdworker-tasks.md
tile.json

tessl/maven-io-cdap-cdap--cdap-system-app-api

API for CDAP System Applications - provides interfaces and abstract classes for building system services that run in the CDAP system namespace

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.cdap.cdap/cdap-system-app-api@6.11.x

To install, run

npx @tessl/cli install tessl/maven-io-cdap-cdap--cdap-system-app-api@6.11.0

index.mddocs/

CDAP System Application API

CDAP System Application API provides interfaces and abstract classes for building system services that run in the CDAP (Cask Data Application Platform) system namespace. This library enables development of system-level applications with enhanced privileges for table creation, namespace administration, and worker task execution.

Package Information

  • Package Name: cdap-system-app-api
  • Package Type: maven
  • Language: Java
  • Installation: Add to Maven pom.xml:
<dependency>
  <groupId>io.cdap.cdap</groupId>
  <artifactId>cdap-system-app-api</artifactId>
  <version>6.11.0</version>
</dependency>

Core Imports

import io.cdap.cdap.api.SystemTableConfigurer;
import io.cdap.cdap.api.service.AbstractSystemService;
import io.cdap.cdap.api.service.SystemServiceContext;
import io.cdap.cdap.api.service.SystemServiceConfigurer;
import io.cdap.cdap.api.service.http.AbstractSystemHttpServiceHandler;
import io.cdap.cdap.api.service.http.SystemHttpServiceContext;
import io.cdap.cdap.api.service.worker.RunnableTask;
import io.cdap.cdap.api.service.worker.RunnableTaskRequest;

Basic Usage

import io.cdap.cdap.api.service.AbstractSystemService;
import io.cdap.cdap.api.service.SystemServiceConfigurer;
import io.cdap.cdap.api.service.SystemServiceContext;
import io.cdap.cdap.spi.data.StructuredTableSpecification;

// Create a system service
public class MySystemService extends AbstractSystemService {
  @Override
  public void configure(SystemServiceConfigurer configurer) {
    setName("my-system-service");
    setDescription("A system service example");
    
    // Create system tables
    StructuredTableSpecification tableSpec = StructuredTableSpecification.builder()
      .withId("my-system-table")
      .withFields(/* field definitions */)
      .build();
    createTable(tableSpec);
  }

  @Override
  protected void startUp() throws Exception {
    // Service initialization
  }

  @Override
  protected void shutDown() throws Exception {
    // Service cleanup
  }
}

Architecture

The CDAP System Application API is organized around several key architectural components:

  • System Services: Base classes and interfaces for creating system-level services that operate with elevated privileges in the CDAP system namespace
  • HTTP Services: Specialized system service handlers for creating web-based APIs and HTTP endpoints with system-level access
  • Worker Tasks: Framework for executing remote tasks on worker nodes with full system context and capabilities
  • System Configuration: Interfaces for configuring system tables and namespace-level operations
  • Exception Handling: Specialized exception classes for handling errors in remote task execution and system operations

All system functionality is restricted to applications deployed in the system namespace and provides capabilities beyond those available to regular user applications.

Capabilities

System Services

Core system service functionality for creating services that run with elevated privileges in the CDAP system namespace. Includes abstract base classes and configuration interfaces.

public abstract class AbstractSystemService 
    extends AbstractService<SystemServiceConfigurer, SystemServiceContext> {
  protected void createTable(StructuredTableSpecification tableSpecification);
}

public interface SystemServiceConfigurer 
    extends ServiceConfigurer, SystemTableConfigurer {
}

public interface SystemServiceContext 
    extends ServiceContext, TransactionRunner, SystemNamespaceAdmin {
}

System Services

HTTP Services

System-level HTTP service handlers for creating web APIs and HTTP endpoints with enhanced system privileges and namespace access.

public abstract class AbstractSystemHttpServiceHandler 
    extends AbstractHttpServiceHandler<SystemHttpServiceContext, SystemHttpServiceConfigurer> {
  protected void createTable(StructuredTableSpecification tableSpecification);
}

public interface SystemHttpServiceContext 
    extends HttpServiceContext, TransactionRunner, SystemNamespaceAdmin {
  byte[] runTask(RunnableTaskRequest runnableTaskRequest) throws Exception;
  boolean isRemoteTaskEnabled();
  ContextAccessEnforcer getContextAccessEnforcer();
  Map<String, String> evaluateMacros(String namespace, Map<String, String> properties, 
                                    MacroEvaluator evaluator, MacroParserOptions options) 
                                    throws InvalidMacroException;
}

HTTP Services

Worker Tasks

Remote task execution framework allowing system services to run tasks on worker nodes with full system context and serializable task parameters.

public interface RunnableTask {
  void run(RunnableTaskContext context) throws Exception;
}

public class RunnableTaskRequest {
  public static Builder getBuilder(String taskClassName);
  public String getClassName();
  public RunnableTaskParam getParam();
  public ArtifactId getArtifactId();
  public String getNamespace();
}

public class RunnableTaskContext {
  public RunnableTaskContext(RunnableTaskRequest taskRequest);
  public void writeResult(byte[] data) throws IOException;
  public ByteBuffer getResult();
}

Worker Tasks

System Table Configuration

Interface for creating and managing system-level tables that persist data in the CDAP system namespace.

public interface SystemTableConfigurer {
  void createTable(StructuredTableSpecification tableSpecification);
}

System table configuration is available through both system services and HTTP services, allowing applications to create persistent storage that is accessible across the entire CDAP system.

Types

// Base exception for remote task execution errors
public class RemoteExecutionException extends Exception {
  public RemoteExecutionException(RemoteTaskException cause);
  public RemoteTaskException getCause();
  public static RemoteExecutionException fromBasicThrowable(BasicThrowable basicThrowable);
}

// Captures stack traces from remote task exceptions  
public class RemoteTaskException extends Exception {
  public RemoteTaskException(String remoteExceptionClassName, String message, Throwable cause);
  public String getRemoteExceptionClassName();
}

// Parameter wrapper for runnable task requests
public class RunnableTaskParam {
  public RunnableTaskParam(String simpleParam, RunnableTaskRequest embeddedTaskRequest);
  public String getSimpleParam();
  public RunnableTaskRequest getEmbeddedTaskRequest();
}