001/*
002 * (C) Copyright 2006-2008 Nuxeo SAS (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     bstefanescu
016 *
017 * $Id$
018 */
019
020package org.nuxeo.ecm.webengine.session;
021
022import java.io.Serializable;
023
024/**
025 * A stateful session component.
026 * <p>
027 * A component is instantiate and activated the first time it is requested. It is destroyed when the user session ends.
028 * <p>
029 * Stateful components are not necessarily thread safe and should be used only from the UserSession thread.
030 *
031 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
032 */
033public interface Component extends Serializable {
034
035    /**
036     * The component was instantiated by the given session.
037     * <p>
038     * This method should initialize the component. After returning the component will become visible in the session.
039     *
040     * @param session the user session that created the component
041     * @param name the name under this component is registered. Can be null for unnamed component.
042     * @throws InvalidStateException if the component is not in an appropriate life cycle state
043     * @throws SessionException an internal error occurred
044     */
045    void initialize(UserSession session, String name) throws SessionException;
046
047    /**
048     * Destroy this component. This is called by the when the owning session is about to be destroyed. The component
049     * should release any allocated resources.
050     *
051     * @param session the session owning this component
052     * @throws InvalidStateException if the component is not in an appropriate life cycle state
053     * @throws SessionException an internal error occurred
054     */
055    void destroy(UserSession session) throws SessionException;
056
057    /**
058     * Get the component name if any. A component may be initialized under a name. For singleton components no name is
059     * needed so this method might return null.
060     *
061     * @return the name if any otherwise null
062     */
063    String getName();
064
065    /**
066     * Checks whether this component was initialized and can be used.
067     */
068    boolean isLive();
069
070}