API Oak

API для доступа к основным функциям Oak находится в пакете org.apache.jackrabbit.oak.api и состоит из следующих ключевых интерфейсов:

• ContentRepository;
• ContentSession;
• Root / Tree.

Интерфейс ContentRepository представляет собой весь репозиторий контента Oak. Репозиторий может быть локальным или удалённым, а также кластером любого размера. Эти детали развёртывания скрыты за этим интерфейсом.

Ответственность за запуск и остановку экземпляров ContentRepository лежит на каждом конкретном развёртывании и не покрывается этими интерфейсами. Клиенты репозитория должны использовать механизм, специфичный для развёртывания (JNDI, сервис OSGi и т. д.), чтобы получить ссылки на экземпляры ContentRepository.

Весь контент в репозитории доступен через аутентифицированные сессии, полученные через метод ContentRepository.login(). Метод принимает явные учётные данные и другие данные для входа и, если учётные данные действительны, возвращает экземпляр ContentSession, который инкапсулирует эту информацию. Экземпляры сессий являются Closeable и должны быть закрыты, чтобы освободить связанные ресурсы, когда они больше не используются. Рекомендуемый шаблон доступа:

ContentRepository repository = ...;
ContentSession session = repository.login(...);
try {
    ...; // Use the session
} finally {
    session.close();
}

Все экземпляры ContentRepository и ContentSession являются потокобезопасными.

Аутентифицированный ContentSession предоставляет вам должным образом авторизованный доступ к иерархическому дереву контента внутри репозитория через экземпляры интерфейсов Root и Tree. Метод getCurrentRoot() возвращает снимок текущего состояния дерева контента:

ContentSession session = ...;
Root root = session.getCurrentRoot();
Tree tree = root.getTree("/");

Возвращённый экземпляр Tree принадлежит клиенту, и его состояние изменяется только в ответ на вызовы методов, сделанные клиентом. Экземпляры Tree не являются потокобезопасными для доступа на запись, поэтому пишущие клиенты должны убедиться, что они не доступны одновременно из нескольких потоков. Экземпляры Tree, являются потокобезопасными для чтения, поэтому реализации должны гарантировать, что все читающие клиенты видят согласованное состояние.

Деревья контента представляют собой рекурсивные структуры данных, которые состоят из именованных свойств и поддеревьев, использующих одно и то же пространство имён, но доступных через отдельные методы, как показано ниже:

Tree tree = ...;
for (PropertyState property : tree.getProperties()) {
    ...;
}
for (Tree subtree : tree.getChildren()) {
    ...;
}

Снимок содержимого репозитория, предоставляемый экземпляром Tree, со временем может стать недействительным из-за сборки мусора старого содержимого, после чего устаревший снимок начнёт выдавать IllegalStateExceptions, чтобы указать, что снимок больше недоступен. Чтобы получить доступ к более свежему содержимому, клиент должен либо вызвать ContentSession.getCurrentRoot(), чтобы получить новый снимок содержимого, либо использовать метод refresh(), чтобы обновить данный Root до последнего состояния репозитория контента:

Root root = ...;
root.refresh();

Помимо чтения содержимого репозитория клиент также может вносить изменения в дерево контента. Такие изменения содержимого остаются локальными для конкретного экземпляра Root (и связанных поддеревьев) до тех пор, пока они явно не будут зафиксированы. Например, следующий код создаёт и фиксирует новое поддерево, содержащее только простое свойство:

ContentSession session = ...;
Root root = session.getCurrentRoot();
Tree tree = root.getTree("/");
Tree subtree = tree.addChild("hello");
subtree.setProperty("message", "Hello, World!");
root.commit();

Даже другие экземпляры Root, полученные от того же ContentSession, не увидят таких изменений, пока они не будут зафиксированы и деревья не обновлены. Это позволяет клиенту отслеживать несколько параллельных наборов изменений с помощью всего одной аутентифицированной сессии.

Лицензия

(см. верхний уровень LICENSE.txt для получения полной информации о лицензии).

Коллективная работа: Copyright 2012 The Apache. Софтвар Фаундейшн.

Лицензировано Фонду программного обеспечения Apache (ASF) в соответствии с одним или несколькими соглашениями о лицензиях участников. Дополнительную информацию об авторских правах см. в файле NOTICE, распространяемом вместе с этой работой.

ASF лицензирует этот файл Вам по лицензии Apache версии 2.0 («Лицензия»); Вы не можете использовать этот файл иначе, чем в соответствии с Лицензией. Вы можете получить копию Лицензии по адресу:

http://www.apache.org/licenses/LICENSE-2.0

Если это не требуется применимым законодательством или не согласовано в письменной форме, программное обеспечение, распространяемое по Лицензии, распространяется на условиях «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ ИЛИ УСЛОВИЙ ЛЮБОГО РОДА, явных или подразумеваемых. См. Лицензию для конкретного языка, регулирующего разрешения и ограничения по Лицензии.