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}