001/*
002 * (C) Copyright 2006-2008 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 *     bstefanescu
018 *
019 * $Id$
020 */
021
022package org.nuxeo.ecm.webengine.session;
023
024import java.io.Serializable;
025
026/**
027 * A stateful session component.
028 * <p>
029 * A component is instantiate and activated the first time it is requested. It is destroyed when the user session ends.
030 * <p>
031 * Stateful components are not necessarily thread safe and should be used only from the UserSession thread.
032 *
033 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
034 */
035public interface Component extends Serializable {
036
037    /**
038     * The component was instantiated by the given session.
039     * <p>
040     * This method should initialize the component. After returning the component will become visible in the session.
041     *
042     * @param session the user session that created the component
043     * @param name the name under this component is registered. Can be null for unnamed component.
044     * @throws InvalidStateException if the component is not in an appropriate life cycle state
045     * @throws SessionException an internal error occurred
046     */
047    void initialize(UserSession session, String name) throws SessionException;
048
049    /**
050     * Destroy this component. This is called by the when the owning session is about to be destroyed. The component
051     * should release any allocated resources.
052     *
053     * @param session the session owning this component
054     * @throws InvalidStateException if the component is not in an appropriate life cycle state
055     * @throws SessionException an internal error occurred
056     */
057    void destroy(UserSession session) throws SessionException;
058
059    /**
060     * Get the component name if any. A component may be initialized under a name. For singleton components no name is
061     * needed so this method might return null.
062     *
063     * @return the name if any otherwise null
064     */
065    String getName();
066
067    /**
068     * Checks whether this component was initialized and can be used.
069     */
070    boolean isLive();
071
072}