Skip to main content

PubServer API Documentation

Introduction​

The PubServerAPI (com.priint.pubserverapi) was created to enable users and external systems to integrate with the publication management system. It provides a set of methods for managing documents, publications, page templates, users, notes, and other system components.

In addition to managing entities like documents and publications, the PubServer API also provides access to cache operations via PriintCacheServiceLocal. This allows developers to programmatically create, retrieve, and clear caches using the PriintCacheManager interface.

1. General API Usage Principles​

To effectively navigate and understand the PubServer API, keep in mind the following common patterns that apply across most service interfaces:

  • Retrieving by ID: Nearly all services provide methods to fetch a single object using its ID (e.g., getDocumentById, getPublicationById). These return an Optional<T> containing the object if it exists.
  • Querying collections: Most interfaces include a method to create a query builder (e.g., createDocumentQuery, createPublicationQuery) that lets you retrieve filtered lists of entities. Fluent API pattern is used for chaining query conditions.
  • Creating new objects: Methods that create resources (like documents or publications) typically return an ID of the newly created entity (e.g., DocumentId, PublicationId).
  • Updating, assigning, or deleting: Operations that modify state without returning data (like update, assignToRoles, deleteById) usually have a void return type.
  • **Service-specific exceptions: Each service typically defines its own subclass of PubServerBaseException for error handling (for example, UserServiceException, DocumentServiceException). Since PubServerBaseException extends RuntimeException, these are unchecked exceptions; you do not need to declare them in a method signature, but you should still handle them appropriately when calling methods that create, update, or retrieve resources.
  • Domain-specific classes: Types such as Document, User, etc. are introduced in this API to represent key entities in the publication management system.

These patterns help maintain a consistent and predictable developer experience when working with different services in the API.

2. Example: Working with DocumentServiceLocal​

This section provides practical examples to help you get started with using the PubServer API. You'll learn how to retrieve services, perform queries, and execute common operations like fetching, updating, and creating documents.

2.1 Getting a Service Interface​

To interact with the API, first obtain a reference to the service you want to use. This is typically done using the PlannerEngineServiceLocator.

The PlannerEngineServiceLocator provides access to the various service interfaces. For instance, to work with documents:

DocumentServiceLocal documentServiceLocal = PlannerEngineServiceLocator.INSTANCE.getDocumentServiceLocal();

This example demonstrates accessing the DocumentServiceLocal, but the same pattern applies to other services such as PublicationServiceLocal, NoteServiceLocal, or UserServiceLocal, which can be retrieved using their corresponding get...() methods from PlannerEngineServiceLocator.INSTANCE.

2.2 Querying Documents by Criteria​

Once you have a service reference, you can create queries to retrieve data based on specific conditions.

Most services provide a way to create a query object. For documents:

List<Document> documents = documentServiceLocal
    .createDocumentQuery()
    .labelLike("test")
    .documentStage(DocumentStage.Preparation)
    .documentType(DocumentType.STATIC)
    .list();

This example filters documents whose label contains "Test", are in the Preparation stage, and are of type STATIC.

2.3. Retrieving a Single Document by ID​

Sometimes you already know the document’s ID:

Optional<Document> documentById = documentServiceLocal.getDocumentById(DocumentId.of("documentId"));
Document document = documentById.orElseGet(() -> {
    throw new ServiceRuntimeException("Document not found");
});

2.4 Updating an Existing Document​

After retrieving a document, you can modify its properties and persist the changes using the update() method.

Once you retrieve a document, you can update its fields:

document.setDocumentTemplateId(DocumentId.of("documentId"));
document.setDocumentStage(DocumentStage.ContentAssignment);
documentServiceLocal.update(document);

2.5. Creating a Document from a Template​

The API also supports creating new documents based on existing templates. This is useful when you want to generate predefined layouts or structures.

Beyond basic CRUD, some services—like DocumentServiceLocal—offer specialized methods. For example, you can create new documents from existing templates using createDocumentFromTemplate, which requires a TemplateId and a name for the new document.

DocumentId documentFromTemplate = documentServiceLocal.createDocumentFromTemplate(
    PublicationId.of(PUBLICATION_ID),
    DocumentId.of("25125421"),
    "test",
    "test"
);

2.6. Additional Non-CRUD Operations​

Below are other examples of advanced operations supported by different services.

2.6.1. Working with User Roles​

UserServiceLocal userServiceLocal = PlannerEngineServiceLocator.INSTANCE.getUserServiceLocal();
// Assign multiple roles to a user
UserId userId = UserId.of("userId");
List<Role> roles = new ArrayList<>();
roles.add(Role.of("role1"));
roles.add(Role.of("role2"));
userServiceLocal.assignRoles(userId, roles);

2.6.2. Assigning a Document Template to a Publication​

PublicationServiceLocal publicationServiceLocal = PlannerEngineServiceLocator.INSTANCE.getPublicationServiceLocal();
// assign document template to publication
PublicationId publicationId = PublicationId.of("publicationId");
DocumentId documentId = DocumentId.of("documentId");
publicationServiceLocal.assignDocumentTemplateToPublication(
    publicationId,
    documentId
);

3. Working with Cache​

The API includes a dedicated cache service interface: PriintCacheServiceLocal, which provides access to the PriintCacheManager. This enables low-level cache operations such as creating, retrieving, and removing cache instances.

Example usage:

PriintCacheServiceLocal cacheService = PlannerEngineServiceLocator.INSTANCE.getPriintCacheServiceLocal();
PriintCacheManager cacheManager = cacheService.getPriintCacheManager();

Available cache operations include:

  • createCache(String name, Class<V> valueType) – Creates a new cache instance.

  • getCache(String name) – Retrieves an existing cache by name.

  • removeCache(String name) – Removes a cache.

  • cacheExists(String name) – Checks if a cache with the given name exists.

3.1 Creating a Cache​

To create a new cache, use the createCache method. You need to specify the cache name and the value type.

PriintCache<String, Object> myCache = cacheManager.createCache("pubserver.myCache", Object.class);
myCache.put("key", "value");

4. Working with Storage​

The API also provides a storage interface PriintStorageServiceLocal for managing file-based media assets and document data. This interface allows operations such as uploading files, duplicating documents, and retrieving streams.

Example usage:

PriintStorageServiceLocal storageService = PlannerEngineServiceLocator.INSTANCE.getPriintStorageServiceLocal();
PriintStorage storage = storageService.getPriintStorage();

// Define constants to be used in the following examples
private static final String tenant = "tenant";
private static final String project = "project";
private static final StorageContext STORAGE_CONTEXT = new StorageContext(project, tenant);

Available storage operations include:

  • getPriintStorage() – Retrieves the main storage instance implementing interface PriintStorage for managing storage operations in the Priint system

Below are some examples of how to use the storage service:

4.1 Uploading a File​

Uploading a file to the storage system is straightforward. You can specify the storage context, the file name, and the file path.

  DocumentDescriptor docDesc = new DocumentDescriptor(STORAGE_CONTEXT, "537393319", DocumentObjectType.W2ML,false);
  storage.uploadObject(docDesc, new File("src/test/resources/test-file.txt"));
  storage.uploadDocumentMetadata(docDesc, "src/test/resources/537393319.w2ml.meta");

4.2 Delete a File​

To delete a file from the storage system, you need to specify the storage context, the file name, and the folder path.

final List<String> folderPath = List.of("test-folder", "within-other-folder");
final String fileName = "test-file-1";
final DownloadFileDescriptor downloadFilePointer = DownloadFileDescriptor.builder()
    .storageContext(STORAGE_CONTEXT)
    .subfolderPath(folderPath)
    .fileName(fileName)
    .build();
storage.deleteObject(downloadFilePointer);

4.3 Listing Files in a Folder​

To list files in a specific folder, you can use the listObjects method. This method returns a FileListing object containing the files in the specified folder.

final List<String> testFolderPath = List.of("test-folder", "within-other-folder");
final FolderDescriptor miscFolderDescriptor = FolderDescriptor.miscFolder(STORAGE_CONTEXT, testFolderPath);
final FileListing fileListing = priintStorage.listObjects(miscFolderDescriptor);
fileListing.forEach(item -> {
    System.out.println(item.getFilename());
});