/*

  * Copyright 2012-2013 smartics, Kronseder & Reiner GmbH

  *

  * Licensed under the Apache License, Version 2.0 (the "License");

  * you may not use this file except in compliance with the License.

  * You may obtain a copy of the License at

  *

  *     http://www.apache.org/licenses/LICENSE-2.0

  *

  * Unless required by applicable law or agreed to in writing, software

  * distributed under the License is distributed on an "AS IS" BASIS,

  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  * See the License for the specific language governing permissions and

  * limitations under the License.

  */

 package de.smartics.properties.api.core.domain;

 import org.apache.commons.lang.StringUtils;

 /**

  * Base exception of the library for signaling an unspecific cause that is

  * concerned with a specific property providing the {@link PropertyDescriptor

  * property declaration} information.

  */

 public class PropertyDescriptorException extends PropertyException

 {

   // ********************************* Fields *********************************

   // --- constants ------------------------------------------------------------

   /**

    * The class version identifier.

    * <p>

    * The value of this constant is {@value}.

    * </p>

    */

   private static final long serialVersionUID = 1L;

   // --- members --------------------------------------------------------------

   /**

    * The descriptor of the property raising the exception.

    *

    * @serial

    */

   private final PropertyDescriptor propertyDescriptor;

   // ****************************** Initializer *******************************

   // ****************************** Constructors ******************************

   /**

    * Constructor.

    *

    * @param message the detail message (which is saved for later retrieval by

    *          the {@link #getMessage()} method).

    * @param cause the cause (which is saved for later retrieval by the

    *          {@link #getCause()} method). (A <tt>null</tt> value is permitted,

    *          and indicates that the cause is nonexistent or unknown.)

    * @param propertyDescriptor the descriptor of the property raising the

    *          exception.

    */

   public PropertyDescriptorException(final String message,

       final Throwable cause, final PropertyDescriptor propertyDescriptor)

   {

     super(message, cause, propertyDescriptor.getKey());

     this.propertyDescriptor = propertyDescriptor;

   }

   /**

    * Constructor.

    *

    * @param message the detail message (which is saved for later retrieval by

    *          the {@link #getMessage()} method).

    * @param propertyDescriptor the descriptor of the property raising the

    *          exception.

    */

   public PropertyDescriptorException(final String message,

       final PropertyDescriptor propertyDescriptor)

   {

     this(message, null, propertyDescriptor);

   }

   /**

    * Constructor.

    *

    * @param cause the cause (which is saved for later retrieval by the

    *          {@link #getCause()} method). (A <tt>null</tt> value is permitted,

    *          and indicates that the cause is nonexistent or unknown.)

    * @param propertyDescriptor the descriptor of the property raising the

    *          exception.

    */

   public PropertyDescriptorException(final Throwable cause,

       final PropertyDescriptor propertyDescriptor)

   {

     this(null, cause, propertyDescriptor);

   }

   // ****************************** Inner Classes *****************************

   // ********************************* Methods ********************************

   // --- init -----------------------------------------------------------------

   // --- get&set --------------------------------------------------------------

   /**

    * Returns the descriptor of the property raising the exception.

    *

    * @return the descriptor of the property raising the exception.

    */

   public final PropertyDescriptor getPropertyDescriptor()

   {

     return propertyDescriptor;

   }

   // --- business -------------------------------------------------------------

   /**

    * Returns information on meta data of the property.

    *

    * @param descriptor the descriptor to use. This method is static to allow it

    *          to be called from subclasses in their constructor.

    * @return information on meta data of the property.

    */

   protected static final String getMetaDataMessage(

       final PropertyDescriptor descriptor)

   {

     final StringBuilder buffer = new StringBuilder(128);

     appendMetaDataMessage(buffer, descriptor);

     return buffer.toString();

   }

   /**

    * Returns information on meta data of the property.

    *

    * @param buffer the buffer to append to.

    * @param descriptor the descriptor to use. This method is static to allow it

    *          to be called from subclasses in their constructor.

    */

   protected static final void appendMetaDataMessage(final StringBuilder buffer,

       final PropertyDescriptor descriptor)

   {

     final PropertyComment comment = descriptor.getComment();

     final String url = descriptor.getContext().getPropertyReportUrl();

     if (StringUtils.isNotBlank(comment.getText()))

     {

       if (buffer.length() > 0)

       {

         buffer.append('\n'); // TODO should be indent. Pretty formatting

                              // needed here.

       }

       buffer.append("    Documentation: ").append(comment);

     }

     if (StringUtils.isNotBlank(url))

     {

       if (buffer.length() > 0)

       {

         buffer.append('\n');

       }

       buffer.append("    For further details, please refer to: ").append(url);

     }

   }

   // --- object basics --------------------------------------------------------

 }