001/*
002        $Id: Setting.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.SettingData;
028
029
030/**
031        This is the base class for all setting items. There are
032        four types of settings:
033        <ul>
034        <li>UserClientSetting: Specific for a user using a client
035                application.
036        <li>UserDefaultSetting: Specific for a user, valid for all
037                client applications.
038        <li>ClientDefaultSetting: Specific for a client application,
039                valid for all users.
040        <li>{@link GlobalDefaultSetting}: Valid for all users and client applications.
041        </ul>
042
043        @author Nicklas
044        @version 2.0
045*/
046public abstract class Setting<D extends SettingData>
047        extends BasicItem<D>
048{
049        /**
050                The type of item represented by this class.
051                @see Item#SETTING
052                @see #getType()
053        */
054        public static final Item TYPE = Item.SETTING;
055
056        /**
057                The maximum length of the name that can be stored in the
058                database. Check the length against this value before calling the
059                {@link #setName(String)} method to avoid exceptions.
060        */
061        public static final int MAX_NAME_LENGTH = SettingData.MAX_NAME_LENGTH;
062
063        /**
064                The maximum length of the value that can be stored in the
065                database. Check the length against this value before calling the
066                {@link #setValue(String)} method to avoid exceptions.
067        */
068        public static final int MAX_VALUE_LENGTH = SettingData.MAX_VALUE_LENGTH;
069
070        /**
071                Get a <code>Setting</code> item when you know the ID.
072
073                @param dc The <code>DbControl</code> which will be used for
074                        permission checking and database access.
075                @param id The ID of the item to load
076                @return The <code>Setting</code> item
077                @throws ItemNotFoundException If an item with the specified 
078                        ID is not found
079                @throws PermissionDeniedException If the logged in user doesn't 
080                        have {@link Permission#READ} permission to the item
081                @throws BaseException If there is another error
082        */
083        public static Setting getById(DbControl dc, int id)
084                throws ItemNotFoundException, PermissionDeniedException, BaseException
085        {
086                Setting s = dc.loadItem(Setting.class, id);
087                if (s == null) throw new ItemNotFoundException("Setting[id="+id+"]");
088                return s;
089        }
090
091        Setting(D settingData)
092        {
093                super(settingData);
094        }
095
096        /*
097                From the BasicItem class
098                -------------------------------------------
099        */
100        /**
101                Settings are never linked to other items.
102                @return FALSE
103        */
104        @Override
105        public boolean isUsed()
106                throws BaseException
107        {
108                return false;
109        }
110        /**
111                Add permissions granted to {@link Item#SETTING}.
112        */
113        @Override
114        void initPermissions(int granted, int denied)
115                throws BaseException
116        {
117                granted |= getSessionControl().getRolePermissions(Item.SETTING);
118                super.initPermissions(granted, denied);
119        }
120        // -------------------------------------------
121
122        /**
123                Get the name of this setting.
124        */
125        public String getName()
126        {
127                return getData().getName();
128        }
129        /**
130                Set the name for this setting.
131                @throws PermissionDeniedException If the logged in user doesn't have
132                        write permission
133                @throws InvalidDataException If the new name is longer than
134                        {@link #MAX_NAME_LENGTH}
135        */
136        public void setName(String name)
137                throws PermissionDeniedException, InvalidDataException
138        {
139                checkPermission(Permission.WRITE);
140                getData().setName(StringUtil.setNotNullString(name, "name", MAX_NAME_LENGTH));
141        }
142
143        /**
144                Get the value of this setting.
145        */
146        public String getValue()
147        {
148                return getData().getValue();
149        }
150        /**
151                Set the value for this setting.
152                @throws PermissionDeniedException If the logged in user doesn't have
153                        write permission
154                @throws InvalidDataException If the new value is longer than
155                        {@link #MAX_VALUE_LENGTH}
156        */
157        public void setValue(String value)
158                throws PermissionDeniedException, InvalidDataException
159        {
160                checkPermission(Permission.WRITE);
161                getData().setValue(StringUtil.setNotNullString(value, "value", MAX_VALUE_LENGTH));
162        }
163}
164