StoryCLM Java SDK

StoryCLM Java SDK позволяет легко интегрировать систему StoryCLM c Вашим приложением на Java. Данная библиотека сделана на базе REST API сервиса StoryCLM и максимально упращает работу с API.

Ниже будет рассказано как устаносить библиотеку, настроить проект для работы с ней и показана работа SDK на конкретных примерах.

Установка

Библиотека StoryCLM Java SDK доступна в центральном maven репозитории.

При использовании системы maven в вашем проекте в pom файле укажите

  <dependency>
	   	<groupId>com.storyclm</groupId>
   	    <artifactId>storyclmsdk</artifactId>
   	    <version>1.0.1</version>
	    <scope>compile</scope>
  </dependency>

Если используется система grandle (например, в проектах для Android), необходимо сначала указать локальный maven репозиторий в качестве источника. Для этого в файле build.gradle добавьте в свойство repositories:

repositories {
  mavenCentral()
}

Затем в dependencies добавьте ссылку на проект:

dependencies {
    compile 'com.storyclm:storyclmsdk:1.0.1'
}

Настройка и получение ключей

Подключение пространств имен

В файл, в котором Вы хотите использовать SDK, необходимо добавить следующий код:

import ru.breffi.storyclmsdk.*;
import ru.breffi.storyclmsdk.Exceptions.*;

Активация API и получение ключей доступа

Для того что бы получить доступ к API своего клиента нужно его активировать на панели администрирования и получить ключ доступа.

Что бы узнать как активировать API, получить ключи доступа и узнать подробную информацию о аутентификации и авторизации в системе нужно ознакомиться с документацией по REST API.

Аутентификация

С помощью фасадного класса StoryCLMConnectorsGenerator для клиента в StoryCLM создается коннектор.

public static StoryCLMServiceConnector GetStoryCLMServiceConnector(String сlientId, String сlientSecret, String username, String password, GsonBuilder gbuilder);

Описание:

По аутентификационным данным создает коннектор для доступа к данным определенного клиента StoryCLM. При каждом запросе к StoryCLM автоматически проверяется наличие и актуальность токена и при необходимости запрашивается новый токен, либо продлевается старый.

Параметры:

clientId - идентификатор клиента.
clientSecret - ключ доступа к API.
username - логин пользователя, под учеткой которого подключается приложение
password - пароль пользователя.
gbuilder - В SDK для сериализации/десериализации объектов используется библиотека GSON.В данном параметре передаются специфические настройки GsonBuilder.

В случае отсутствия username и password указывается null. При этом будет использоваться аутентификация типа Service. Для аутентификации приложений типа Application необходмио указать username и password отличными от нуля.

Возвращаемое значение:

коннектор для доступа к данным

Пример

StoryCLMServiceConnector clientConnector = GetStoryCLMServiceConnector("your_сlientId", "your_сlientSecret","user_login","user_password", null);

В данном примере дополнительная настройка конвертации GsonBuilder не требуется.

Коннектор используется для получения сервисов доступа к контенту (презентации, слайды, медиафайлы) и доступа к таблицам.

Токен доступа

Коннектор предоставляет сервисы работы с системой StoryCLM, которые описаны ниже. Помимо этого он позволяет получить токен доступа для авторизации на ресурсах, использующих StoryCLM SSO (Single Sign-On). Для этого используется метод getAccessTokenManager() , возвращающий объект класса AccessTokenManager. Данный менеджер используется для аутентификации в StoryCLM. Его метод getAuthority() возвращает данные для авторизации, в том числе токен доступа. Перед возвращением токен проверяется на время жизни и при необходимости обновляется.

Пример

StoryCLMServiceConnector clientConnector = StoryCLMConnectorsGenerator.GetStoryCLMServiceConnector("your_сlientId", "your_сlientSecret", "login", "password", null);
AccessTokenManager accessTokenManager = clientConnector.getAccessTokenManager();
String access_token = accessTokenManager.checkAndReturnAuthEntityAsync().GetResult().access_token;

Сервис доступа к контенту

Коннектор, полученный при аутентификации на предыдущем шаге позволяет получить сервис доступа к контенту. Используется следующий метод:

public StoryCLMContentService GetContentService()

Описание: Метод получения сервиса доступа к контенту.

Параметры отсутствуют

Возвращаемое значение Сервис доступа к контенту StoryCLM. Данный сервис предоставляет ряд методов для получения информации о клиентах, презентациях, слайдах, медиафайлах и .д.

Пример

  StoryCLMContentService contentService = clientConnector.GetContentService();

Методы доступа к контенту

Все методы сервисов доступа возвращают объект удовлетворяющий интерфейсу IAsyncResult, который позволяет получать данные в асинхронном режиме. Примеры использования в интеграционных тестах.

public interface IAsyncResult<T> {

    /**
     * Возвращает данные в синхронном режиме. Результат непосредственно необходимое значение 
     * @return
     * @throws AsyncResultException - ошибка при получении данных
     * @throws AuthFaliException - ошибка аутентификации
     */
    public T GetResult()  throws AsyncResultException, AuthFaliException;

    /**
     * Метод асинхронного доступа к данным. Не блокирует вызывающий поток.
     * Результаты запроса передаются объекту callback
     * @param callback 
     * Объект обратного вызова. 
     * При успешном получении данных вызывается метод OnSuccess(T result), куда передается полученный результат
     * При ошибке вызывается метод OnFail(Throwable t) с информацией об ошибке.
     */
    public void OnResult(OnResultCallback<T> callback);

}

Метод IAsyncResult<Client[]> GetClients()

Описание

Возвращает информацию о клиентах, которым принадлежит пользователь. Описание типа Client

Метод IAsyncResult<Client> GetClient(int clientid)

Описание Возвращает информацию о клиенте с идентификатором clientId

Метод IAsyncResult<StoryPresentation> GetPresentation(int presentationid)

Описание Возвращает информацию о презентации с идентификатором presentationid. Описание типа StoryPresentation

Метод IAsyncResult<PresentationUser[]> AddPresentationUsers(int presentationId, String[] usersIds)

Описание Добавляет пользователей к презентации. Возвращает список пользователей, которым доступна презентация.

Метод IAsyncResult<PresentationUser[]> RemovePresentationUsers(int presentationId, String[] usersIds)

Описание Удаляет пользователей из презентации. Возвращает список пользователей, которым доступна презентация.

Метод IAsyncResult<PresentationUser[]> SetPresentationUsers(int presentationId, String[] usersIds)

Описание Устанавливает пользователей для презентации. В результате презентация станет доступна тем и только тем пользователям, которые указаны в аргументе usersIds. Возвращает список пользователей, которым доступна презентация.

Метод IAsyncResult<StoryMediafile> GetMediafile(int mediafileId)

Описание Возвращает информацию о медиафайле с идентификатором mediafileId. Описание типа StoryMediafile

Метод IAsyncResult<StorySlide> GetSlide(int slideId)

Описание Возвращает информацию о слайде с идентификатором slideId. Описание типа StorySlide

Метод IAsyncResult<StoryContentPackage> GetSlide(int presentationId)

Описание Возвращает информацию о пакете презентации с идентификатором presentationId. Описание типа StoryContentPackage

Сервис доступа к данным пользователя

Коннектор (класс StoryCLMServiceConnector), полученный при аутентификации позволяет получить сервис доступа к пользовательским данным. Используется следующий метод:

public StoryCLMUserService GetUserService()

Описание: Метод получения сервиса доступа к пользовательским данным.

Параметры отсутствуют

Возвращаемое значение Сервис доступа к пользователям StoryCLM. Данный сервис предоставляет ряд методов для получения информации о пользователях, и управления ими.

Пример

  StoryCLMUserService userService = clientConnector.GetUserService();

Методы доступа к данным пользователя

Метод IAsyncResult<CreateUser> Create(CreateUser user)

Описание Создает пользователя в StoryCLM по модели user

Параметры CreateUser user - данные пользователя

Возвращаемое значение
Объект класса CreateUser, содержащий данные о созданном пользователе, включая полученный идентификатор (поле id)

Метод IAsyncResult<User> Update(User user)

Описание Обновляет данные пользователя в StoryCLM по модели user

Параметры User user - новые данные пользователя

Возвращаемое значение
Объект класса User, содержащий обновленные данные

Метод IAsyncResult<SimpleUser[]> GetUsers()

Описание Возвращает список краткой информации о всех пользователях клиента

Параметры отсутствуют

Возвращаемое значение
Массив SimpleUser[], содержащий краткую информацию о пользователях

Метод IAsyncResult<User> Exists(String username)

Описание Проверяет наличие пользователя в системе StoryCLM

Параметры String username - имя пользователя

Возвращаемое значение
Объект класса User, если пользователь существует и null в противном случае

Метод IAsyncResult<User> Get(String userId)

Описание Возвращает пользователя с идентификатором userId

Параметры String userId - идентификатор пользователя

Возвращаемое значение
Объект класса User, содержащий данные пользователя