/**

  * Licensed to the Apache Software Foundation (ASF) under one

  * or more contributor license agreements.  See the NOTICE file

  * distributed with this work for additional information

  * regarding copyright ownership.  The ASF licenses this file

  *  to you 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 org.apache.creadur.whisker.model;

 import java.util.Collection;

 import java.util.Collections;

 import java.util.Map;

 import java.util.Set;

 /**

  * Describes a software license.

  */

 public class License implements Comparable<License> {

     /**

      * Is information about source distribution required 

      * by this license? 

      */

     private final boolean isSourceRequired;

     /** Template for license wording. */

     private final String baseText;

     /** Parameters expected by the template. */

     private final Collection<String> expectedParameters;

     /** Identifies this license. */

     private final String id;

     /** Canonical locator for this license. */

     private final String url;

     /** Names this license */

     private final String name;

     /**

      * Constructs meta-data for a family of licenses.

      * @param isSourceRequired true if this license requires

      * information about source distribution to be included

      * within the distribution

      * @param baseText a template for the legal text, not null

      * @param expectedParameters not null

      * @param id not null

      * @param url not null

      * @param name not null

      */

     public License(final boolean isSourceRequired, final String baseText,

             final Collection<String> expectedParameters, final String id,

             final String url, final String name) {

         super();

         this.isSourceRequired = isSourceRequired;

         this.baseText = baseText;

         this.expectedParameters = Collections

                 .unmodifiableCollection(expectedParameters);

         this.id = id;

         this.url = url;

         this.name = name;

     }

     /**

      * Is source information inclusion required by this

      * license?

      * @return true when information about the source

      * should be included, false otherwise

      */

     public boolean isSourceRequired() {

         return this.isSourceRequired;

     }

     /**

      * Gets legal text expressing this license.

      * @return not null

      * @throws LicenseTemplateException when the text cannot

      * be created from the template

      */

     public String getText() throws LicenseTemplateException {

         return getText(null);

     }

     /**

      * Gets legal text expressing this license,

      * 

      * @param parameters possibly null

      * @return not null

      * @throws LicenseTemplateException when the text cannot

      * be created from the template

      */

     public String getText(final Map<String, String> parameters)

             throws LicenseTemplateException {

         return substituteInto(validate(parameters), this.baseText);

     }

     /**

      * Gets parameters required by the template

      * to generate a instance of this license family.

      * @return not null, possibly empty

      */

     public Collection<String> getExpectedParameters() {

         return this.expectedParameters;

     }

     /**

      * Validates that these given parameters

      * are suitable for the template expressing the legalise.

      * @param parameters possibly null

      * @return parameters, not null

      * @throws LicenseTemplateException when the parameter

      * do not fulfill the expectations of the template

      */

     @SuppressWarnings("unchecked")

     private Map<String, String> validate(final Map<String, String> parameters)

             throws LicenseTemplateException {

         if (parameters == null) {

             return validate(Collections.EMPTY_MAP);

         }

         if (this.expectedParameters.isEmpty() && parameters != null

                 && !parameters.isEmpty()) {

             throw LicenseTemplateException.notLicenseTemplate(parameters,

                     getName());

         }

         if (!parametersMatch(parameters, this.expectedParameters)) {

             throw LicenseTemplateException.parameterMismatch(

                     this.expectedParameters, parameters.keySet(), getName());

         }

         return parameters;

     }

     /**

      * Do the presented parameters fulfill expectations? 

      * @param parameters possibly null

      * @param expectedParameters possibly null

      * @return true when expected and presented parameters

      * match, false otherwise

      */

     private boolean parametersMatch(final Map<String, String> parameters,

             final Collection<String> expectedParameters) {

         final Set<String> keySet = parameters.keySet();

         return (keySet.containsAll(expectedParameters) && expectedParameters

                 .containsAll(keySet));

     }

     /**

      * Translates a parameter name to 

      * the variable style used by the template

      * @param parameterName not null

      * @return variable in template format, not null

      */

     private String variable(final String parameterName) {

         return "${" + parameterName + "}";

     }

     /**

      * Substitutes parameter values into the variable

      * in the template legalise, parameterising 

      * an instance of the license family.

      * @param parameters not null

      * @param text template text

      * @return not null

      */

     private String substituteInto(final Map<String, String> parameters,

             final String text) {

         String result = text;

         for (final Map.Entry<String, String> entry : parameters.entrySet()) {

             result = result.replace(variable(entry.getKey()), entry.getValue());

         }

         return result;

     }

     /**

      * Stores the license by its id.

      * @param map not null

      * @return the license stored

      */

     public License storeIn(final Map<String, License> map) {

         map.put(getId(), this);

         return this;

     }

     /**

      * Gets the unique identifier for this license.

      * @return not null

      */

     public String getId() {

         return this.id;

     }

     /**

      * Gets a locator for this license.

      * @return not null

      */

     public String getURL() {

         return this.url;

     }

     /**

      * Gets a name for this license suitable for 

      * display.

      * @return not null

      */

     public String getName() {

         return this.name;

     }

     /**

      * @see java.lang.Object#hashCode()

      */

     @Override

     public int hashCode() {

         return getId().hashCode();

     }

     /**

      * @see java.lang.Object#equals(java.lang.Object)

      */

     @Override

     public boolean equals(final Object obj) {

         if (this == obj) {

             return true;

         }

         if (obj == null) {

             return false;

         }

         if (getClass() != obj.getClass()) {

             return false;

         }

         final License other = (License) obj;

         return getId().equals(other);

     }

     /**

      * @see java.lang.Comparable#compareTo(java.lang.Object)

      */

     public int compareTo(final License other) {

         final int nameDifference = getName().compareTo(other.getName());

         return nameDifference == 0 ? getId().compareTo(other.getId())

                 : nameDifference;

     }

     @Override

     public String toString() {

         return "License [id=" + this.id + ", name=" + this.name + "]";

     }

 }