001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (http://www.alkacon.com)
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 *
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * For further information about Alkacon Software, please see the
018 * company website: http://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: http://www.opencms.org
022 *
023 * You should have received a copy of the GNU Lesser General Public
024 * License along with this library; if not, write to the Free Software
025 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
026 */
027
028package org.opencms.main;
029
030import org.opencms.i18n.CmsMessageContainer;
031
032import java.util.ArrayList;
033import java.util.Collections;
034import java.util.Iterator;
035import java.util.List;
036import java.util.Locale;
037
038/**
039 * A multi exception is a container for several exception messages that may be caused by an internal operation.<p>
040 *
041 * This is provided so that the user can see a full picture of all the issues that have been caused in an operation,
042 * rather then only one (usually the first) issue.
043 *
044 * @since 2.0.0
045 */
046public class CmsMultiException extends CmsException {
047
048    /** Serial version UID required for safe serialization. */
049    private static final long serialVersionUID = 1197300254684159700L;
050
051    /** The list of internal exceptions. */
052    protected List<CmsException> m_exceptions;
053
054    /** Indicates if the message has been set as individual message. */
055    protected boolean m_individualMessage;
056
057    /**
058     * Creates a new multi exception, a container for several exception messages.<p>
059     */
060    public CmsMultiException() {
061
062        this(Messages.get().container(Messages.ERR_MULTI_EXCEPTION_1, Integer.valueOf(0)));
063    }
064
065    /**
066     * Creates a new multi exception using the given base message.<p>
067     *
068     * @param message the basic message to use
069     */
070    public CmsMultiException(CmsMessageContainer message) {
071
072        super(message);
073        m_exceptions = new ArrayList<CmsException>();
074        setMessage(message);
075    }
076
077    /**
078     * Creates a new multi exception for the given list of <code>{@link CmsException}</code> instances.<p>
079     *
080     * @param exceptions a list of <code>{@link CmsException}</code> instances
081     */
082    public CmsMultiException(List<CmsException> exceptions) {
083
084        this();
085        setExceptions(exceptions);
086    }
087
088    /**
089     * Adds an Exception to the list of Exceptions kept in this multi Exception.<p>
090     *
091     * @param exception the Exception to add
092     */
093    public void addException(CmsException exception) {
094
095        m_exceptions.add(exception);
096        updateMessage();
097    }
098
099    /**
100     * Adds all Exceptions in the given List to the list of Exceptions kept in this multi Exception.<p>
101     *
102     * @param exceptions the Exceptions to add
103     */
104    public void addExceptions(List<CmsException> exceptions) {
105
106        m_exceptions.addAll(exceptions);
107        updateMessage();
108    }
109
110    /**
111     * @see org.opencms.main.CmsException#createException(org.opencms.i18n.CmsMessageContainer, java.lang.Throwable)
112     */
113    @Override
114    public CmsException createException(CmsMessageContainer container, Throwable cause) {
115
116        if (cause instanceof CmsMultiException) {
117            CmsMultiException multiException = (CmsMultiException)cause;
118            return new CmsMultiException(multiException.getExceptions());
119        }
120        // not a multi exception, use standard handling
121        return super.createException(container, cause);
122    }
123
124    /**
125     * Returns the (unmodifiable) List of exceptions that are stored in this multi exception.<p>
126     *
127     * @return the (unmodifiable) List of exceptions that are stored in this multi exception
128     */
129    public List<CmsException> getExceptions() {
130
131        return Collections.unmodifiableList(m_exceptions);
132    }
133
134    /**
135     * Returns a localized message composed of all contained exceptions.<p>
136     *
137     * @see java.lang.Throwable#getLocalizedMessage()
138     */
139    @Override
140    public String getLocalizedMessage() {
141
142        if (m_exceptions.isEmpty()) {
143            return null;
144        }
145        StringBuffer result = new StringBuffer(128);
146        Iterator<CmsException> it = m_exceptions.iterator();
147        while (it.hasNext()) {
148            CmsException ex = it.next();
149            result.append(ex.getLocalizedMessage());
150            if (it.hasNext()) {
151                result.append('\n');
152            }
153        }
154        return result.toString();
155    }
156
157    /**
158     * Returns a localized message for the given locale composed of all contained exceptions.<p>
159     *
160     * @see org.opencms.main.I_CmsThrowable#getLocalizedMessage(java.util.Locale)
161     */
162    @Override
163    public String getLocalizedMessage(Locale locale) {
164
165        if (m_exceptions.isEmpty()) {
166            return null;
167        }
168        StringBuffer result = new StringBuffer(128);
169        Iterator<CmsException> it = m_exceptions.iterator();
170        while (it.hasNext()) {
171            CmsException ex = it.next();
172            result.append(ex.getLocalizedMessage(locale));
173            if (it.hasNext()) {
174                result.append('\n');
175            }
176        }
177        return result.toString();
178    }
179
180    /**
181     * Returns the individual message (if set) or an empty String.<p>
182     *
183     * @param locale the locale for the message to generate
184     * @return the individual message (if set) or an empty String
185     */
186    public String getMessage(Locale locale) {
187
188        if (hasIndividualMessage()) {
189            return m_message.key(locale);
190        }
191        return "";
192    }
193
194    /**
195     * Returns <code>true</code> if this multi exceptions contains at last one individual Exception.<p>
196     *
197     * @return <code>true</code> if this multi exceptions contains at last one individual Exception
198     */
199    public boolean hasExceptions() {
200
201        return !m_exceptions.isEmpty();
202    }
203
204    /**
205     * Returns <code>true</code> if this multi message has an individual base message set.<p>
206     *
207     * @return <code>true</code> if this multi message has an individual base message set
208     *
209     * @see #setMessage(CmsMessageContainer)
210     */
211    public boolean hasIndividualMessage() {
212
213        return m_individualMessage;
214    }
215
216    /**
217     * Sets an individual message for the multi exception base message.<p>
218     *
219     * If no individual message has been set, a default message using the key
220     * <code>{@link org.opencms.main.Messages#ERR_MULTI_EXCEPTION_1}</code> will be used.<p>
221     *
222     * If <code>null</code> is given as parameter, any individual message that
223     * has been set is reset to the default message.<p>
224     *
225     * @param message the message to set
226     */
227    public void setMessage(CmsMessageContainer message) {
228
229        if ((message != null) && (message.getKey() != Messages.ERR_MULTI_EXCEPTION_1)) {
230            m_individualMessage = true;
231            m_message = message;
232        } else {
233            // if message is null, reset and use default message again
234            m_individualMessage = false;
235            updateMessage();
236        }
237    }
238
239    /**
240     * Updates the internal list of stored exceptions.<p>
241     *
242     * @param exceptions the exceptions to use (will replace the current exception list)
243     */
244    protected void setExceptions(List<CmsException> exceptions) {
245
246        m_exceptions = new ArrayList<CmsException>(exceptions);
247        updateMessage();
248    }
249
250    /**
251     * Updates the intenal message for the Exception.<p>
252     */
253    protected void updateMessage() {
254
255        if (!hasIndividualMessage()) {
256            m_message = Messages.get().container(Messages.ERR_MULTI_EXCEPTION_1, Integer.valueOf(m_exceptions.size()));
257        }
258    }
259}