001/*
002 $Id: Client.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.ClientData;
028
029/**
030 * This class represents a registered client application. Registering a client
031 * application has some benefits:
032 * <ul>
033 * <li>It is possible to create and store settings
034 * <li>It is possible to set permissions for the usage of the application
035 * </ul>
036 * 
037 * @author Nicklas
038 * @version 2.0
039 */
040public class Client
041                extends CommonItem<ClientData>
042{
043        /**
044         * The type of item represented by this class.
045         * 
046         * @see Item#CLIENT
047         * @see #getType()
048         */
049        public static final Item TYPE = Item.CLIENT;
050        /**
051         * The maximum length of the external id variable that can be stored in the
052         * database. Check the length against this value before calling the
053         * {@link #setExternalId(String)} method to avoid exceptions.
054         */
055        public static final int MAX_EXTERNAL_ID_LENGTH = ClientData.MAX_EXTERNAL_ID_LENGTH;
056
057
058        /**
059         * Get a <code>Client</code> item when you know the external ID.
060         * 
061         * @param dc The <code>DbControl</code> which will be used for permission
062         *        checking and database access.
063         * @param externalId The external id of the item to load
064         * @return The <code>Client</code> item
065         * @throws ItemNotFoundException If an item with the specified ID is not
066         *         found
067         * @throws PermissionDeniedException If the logged in user doesn't have
068         *         {@link Permission#READ READ} permission for the item
069         * @throws BaseException If there is another error
070         */
071        public static Client getByExternalId(DbControl dc, String externalId)
072                        throws ItemNotFoundException, PermissionDeniedException,
073                        BaseException
074        {
075                org.hibernate.Query query = HibernateUtil.getPredefinedQuery(dc
076                        .getHibernateSession(), "GET_CLIENT_FOR_EXTERNAL_ID");
077                /*
078                 * SELECT cli FROM ClientData cli WHERE cli.externalId = :externalId
079                 */
080                query.setString("externalId", externalId);
081                Client c = dc.getItem(Client.class, HibernateUtil.loadData(
082                        ClientData.class, query));
083                if (c == null)
084                        throw new ItemNotFoundException(
085                                "Client[externalId=" + externalId + "]");
086                return c;
087        }
088
089
090        /**
091         * Get a new query object for this class.
092         * 
093         * @return An {@link ItemQuery} object
094         */
095        public static ItemQuery<Client> getQuery()
096        {
097                return new ItemQuery<Client>(Client.class);
098        }
099
100
101        Client(ClientData clientData)
102        {
103                super(clientData);
104        }
105
106
107        /*
108         * From the Identifiable interface
109         * -------------------------------------------
110         */
111        public Item getType()
112        {
113                return TYPE;
114        }
115
116
117        // -------------------------------------------
118        /*
119         * From the BasicItem class -------------------------------------------
120         */
121        /**
122         * Always return FALSE. A client can be referenced from help, sessions and
123         * settings but those references are automatically deleted if the client is
124         * deleted and aren't inclued in this check.
125         */
126        @Override
127        public boolean isUsed()
128                        throws BaseException
129        {
130                return false;
131        }
132
133
134        // -------------------------------------------
135        /**
136         * Get the external id for this <code>Client</code> item.
137         * 
138         * @return A string with the external id of this item
139         */
140        public String getExternalId()
141        {
142                return getData().getExternalId();
143        }
144
145
146        /**
147         * Set the external id for this <code>Client</code> item. The value cannot
148         * be null and must not be longer than the value specified by the
149         * {@link #MAX_EXTERNAL_ID_LENGTH} constant.
150         * 
151         * @param externalId The new external id for this item
152         * @throws PermissionDeniedException If the logged in user doesn't have
153         *         write permission
154         * @throws InvalidDataException If the new value is null or longer than
155         *         {@link #MAX_EXTERNAL_ID_LENGTH}
156         */
157        public void setExternalId(String externalId)
158                        throws PermissionDeniedException, InvalidDataException
159        {
160                checkPermission(Permission.WRITE);
161                getData().setExternalId(
162                        StringUtil.setNotNullString(externalId, "externalId",
163                                MAX_EXTERNAL_ID_LENGTH));
164        }
165}