001/*
002 * (C) Copyright 2016 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Florent Guillaume
018 */
019package org.nuxeo.ecm.core.api;
020
021import java.util.List;
022
023/**
024 * Service managing the acquisition/release of {@link CoreSession} instances.
025 *
026 * @since 8.4
027 */
028public interface CoreSessionService {
029
030    /**
031     * Debug information about a {@link CoreSession} acquisition.
032     * <p>
033     * Since 10.3, we also store the closing stacktrace as a suppressed exception.
034     */
035    static class CoreSessionRegistrationInfo extends Throwable {
036
037        private static final long serialVersionUID = 1L;
038
039        protected CloseableCoreSession session;
040
041        public CoreSessionRegistrationInfo(CloseableCoreSession session) {
042            super("DEBUG: opening stacktrace, sessionId=" + session.getSessionId() + ", thread="
043                    + Thread.currentThread().getName());
044            this.session = session;
045        }
046
047        public CoreSession getCoreSession() {
048            return session;
049        }
050    }
051
052    /**
053     * Instantiates a {@link CoreSession}.
054     *
055     * @param repositoryName the repository name
056     * @param principal the principal
057     * @return a {@link CloseableCoreSession}
058     */
059    CloseableCoreSession createCoreSession(String repositoryName, NuxeoPrincipal principal);
060
061    /**
062     * Releases (closes) a {@link CloseableCoreSession} acquired by {@link #createCoreSession}.
063     *
064     * @param session the session to close
065     */
066    void releaseCoreSession(CloseableCoreSession session);
067
068    /**
069     * Gets an existing open session for the given session id.
070     * <p>
071     * The returned {@link CoreSession} must not be closed, as it is owned by someone else.
072     *
073     * @param sessionId the session id
074     * @return the session, which must not be closed
075     */
076    CoreSession getCoreSession(String sessionId);
077
078    /**
079     * Gets the number of open sessions.
080     */
081    int getNumberOfOpenCoreSessions();
082
083    /**
084     * Gets the debug info for the open sessions.
085     *
086     * @return a list of debug info
087     */
088    List<CoreSessionRegistrationInfo> getCoreSessionRegistrationInfos();
089
090}