001/*
002        $Id: Session.java 3207 2009-04-09 06:48:11Z gregory $
003
004        Copyright (C) 2006 Gregory Vincic, Olle Mansson
005        Copyright (C) 2007 Gregory Vincic
006
007        This file is part of Proteios.
008        Available at http://www.proteios.org/
009
010        Proteios is free software; you can redistribute it and/or modify it
011        under the terms of the GNU General Public License as published by
012        the Free Software Foundation; either version 2 of the License, or
013        (at your option) any later version.
014
015        Proteios is distributed in the hope that it will be useful, but
016        WITHOUT ANY WARRANTY; without even the implied warranty of
017        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
018        General Public License for more details.
019
020        You should have received a copy of the GNU General Public License
021        along with this program; if not, write to the Free Software
022        Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
023        02111-1307, USA.
024*/
025package org.proteios.core;
026
027import org.proteios.core.data.SessionData;
028import org.proteios.core.query.Hql;
029import org.proteios.core.query.Restrictions;
030import java.util.Date;
031
032/**
033        A session represents the time between login and logout for a single
034        user. Hence, a session item is automatically created when a user
035        logs in, and is automatically updated when the user logs out.
036        <p>
037        A session said to be active when the user is logged in. 
038
039        @author Nicklas
040        @version 2.0
041*/
042public class Session
043        extends BasicItem<SessionData>
044{
045        /**
046                The type of item represented by this class.
047                @see Item#SESSION
048                @see #getType()
049        */
050        public static final Item TYPE = Item.SESSION;
051
052        /**
053                Get a <code>Session</code> item when you know the ID.
054
055                @param dc The <code>DbControl</code> which will be used for
056                        permission checking and database access.
057                @param id The ID of the item to load
058                @return The <code>Session</code> item
059                @throws ItemNotFoundException If an item with the specified 
060                        ID is not found
061                @throws PermissionDeniedException If the logged in user doesn't 
062                        have {@link Permission#READ} permission to the item
063                @throws BaseException If there is another error
064        */
065        public static Session getById(DbControl dc, int id)
066                throws ItemNotFoundException, PermissionDeniedException, BaseException
067        {
068                Session s = dc.loadItem(Session.class, id);
069                if (s == null) throw new ItemNotFoundException("Session[id="+id+"]");
070                return s;
071        }
072
073        /**
074                Get a query configured to retrieve sessions for the specified user.
075                
076                @param user The user to retreive sessions for, null is allowed if
077                        the logged in user has generic READ permission for sessions in which case
078                        all sessions will be returned
079                @return An {@link ItemQuery} object
080        */
081        public static ItemQuery<Session> getQuery(User user)
082        {
083                ItemQuery<Session> query = null;
084                
085                if (user != null)
086                {
087                        query = new ItemQuery<Session>(Session.class, null);
088                        query.restrictPermanent(
089                                Restrictions.eq(
090                                        Hql.property("user"), 
091                                        Hql.entity(user)
092                                )
093                        );
094                }
095                else
096                {
097                        query = new ItemQuery<Session>(Session.class);
098                }
099                return query;
100        }
101
102        Session(SessionData sessionData)
103        {
104                super(sessionData);
105        }
106
107        /*
108                From the Identifiable interface
109                -------------------------------------------
110        */
111        public Item getType()
112        {
113                return TYPE;
114        }
115        // -------------------------------------------
116
117        /*
118                From the BasicItem class
119                -------------------------------------------
120        */
121        /**
122                Always return FALSE.
123                A session is not referenced from other items.
124        */
125        @Override
126        public boolean isUsed()
127                throws BaseException
128        {
129                return false;
130        }
131        /**
132                READ permission is granted if the logged in user is the owner of this
133                session. All other permissions are denied.
134        */
135        @Override
136        void initPermissions(int granted, int denied)
137                throws BaseException
138        {
139                if (getSessionControl().getLoggedInUserId() == getData().getUser().getId())
140                {
141                        granted |= Permission.grant(Permission.READ);
142                }
143                denied |= Permission.deny(Permission.WRITE);
144                super.initPermissions(granted, denied);
145        }
146        // -------------------------------------------
147
148        /**
149                Get the user that logged in with this session.
150
151                @return The <code>User</code> item
152                @throws PermissionDeniedException If the logged in user doesn't have 
153                        {@link Permission#READ} permission
154                @throws BaseException If there is another error
155        */
156        public User getUser()
157                throws PermissionDeniedException, BaseException
158        {
159                return getDbControl().getItem(User.class, getData().getUser());
160        }
161
162        /**
163                Get the client application the user was using in this session.
164
165                @return A <code>Client</code> item, or null if not known
166                @throws PermissionDeniedException If the logged in user doesn't 
167                        have {@link Permission#READ} permission
168                @throws BaseException If there is another error
169        */
170        public Client getClient()
171                throws PermissionDeniedException, BaseException
172        {
173                return getDbControl().getItem(Client.class, getData().getClient());
174        }
175
176        /**
177                Get the date and time the user logged in.
178                @return A <code>Date</code> object with the login time
179        */
180        public Date getLoginTime()
181        {
182                return DateUtil.copy(getData().getLoginTime());
183        }
184
185        /**
186                Get the date and time the user logged out.
187                @return A <code>Date</code> object with the logout time
188        */
189        public Date getLogoutTime()
190        {
191                return DateUtil.copy(getData().getLogoutTime());
192        }
193
194        /**
195                Get the login comment.
196                @return A <code>String</code> object with the login comment
197        */
198        public String getLoginComment()
199        {
200                return getData().getLoginComment();
201        }
202
203        /**
204                Check if another user was acting as the user of this session.
205                @return TRUE if the user was impersonated, FALSE otherwise
206        */
207        public boolean getImpersonated()
208        {
209                return getData().getImpersonated();
210        }
211
212        /**
213                Get the remote ID of the host the user used for this session.
214                Typically it is the IP-address of the user's computer.
215                @return A <code>String</code> object with remote ID
216        */
217        public String getRemoteId()
218        {
219                return getData().getRemoteId();
220        }
221
222}
223
224
225