Constraint


1   /* ValueConstraint
2    *
3    * $Id: Constraint.java,v 1.4.16.1 2007/01/13 01:31:26 stack-sf Exp $
4    *
5    * Created on Mar 29, 2004
6    *
7    * Copyright (C) 2004 Internet Archive.
8    *
9    * This file is part of the Heritrix web crawler (crawler.archive.org).
10   *
11   * Heritrix is free software; you can redistribute it and/or modify
12   * it under the terms of the GNU Lesser Public License as published by
13   * the Free Software Foundation; either version 2.1 of the License, or
14   * any later version.
15   *
16   * Heritrix is distributed in the hope that it will be useful,
17   * but WITHOUT ANY WARRANTY; without even the implied warranty of
18   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19   * GNU Lesser Public License for more details.
20   *
21   * You should have received a copy of the GNU Lesser Public License
22   * along with Heritrix; if not, write to the Free Software
23   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
24   */
25  package org.archive.crawler.settings;
26  
27  import java.io.Serializable  ;
28  import java.text.MessageFormat  ;
29  import java.util.ArrayList  ;
30  import java.util.logging.Level  ;
31  
32  
33  /**
34   * Superclass for constraints that can be set on attribute definitions.
35   * <p>
36   * Constraints will be checked against attribute values. If a constraint check
37   * fails, an object of type FailedCheck is returned containing information that
38   * can be used to build meaningful information to the user.
39   * <p>
40   * A constraint has one of three levels:
41   * <ul>
42   * <li>{@link java.util.logging.Level#SEVERE}The attribute could not be set
43   * whatsoever.
44   * <li>{@link java.util.logging.Level#WARNING}The attribute is illegal i
45   * CrawlJobs, but could be set in profiles. Mostly used as holder value for
46   * settings that should be changed for every entity running a crawl.
47   * <li>{@link java.util.logging.Level#INFO}The attribute has a legal value,
48   * but is outside the bounds of what are considered a reasonable value. The user
49   * could be warned that she should investigate if the value actally is what she
50   * wants it be.
51   * </ul>
52   *
53   * @author John Erik Halse
54   */
55  public abstract class Constraint 
56  implements Comparable  <Constraint>, Serializable   {
57      private final Level   severity;
58      private final String   msg;
59  
60      /** Constructs a new Constraint.
61       *
62       * @param level the level for this constraint.
63       * @param msg default message to return if the check fails.
64       */
65      public Constraint(Level   level, String   msg) {
66          if (level != Level.SEVERE && level != Level.WARNING
67                  && level != Level.INFO) {
68              throw new IllegalArgumentException  ("Illegal level: "
69                      + level.getName());
70          }
71          this.severity = level;
72          this.msg = msg;
73      }
74  
75      /**
76       * Run the check.
77       *
78       * @param owner the ComplexType owning the attribute to check.
79       * @param definition the definition to check the attribute against.
80       * @param value the value to check.
81       * @return null if ok, or an instance of {@link FailedCheck}if the check
82       *         failed.
83       */
84      public final FailedCheck check(CrawlerSettings settings, ComplexType owner,
85              Type definition, Object   value) {
86          return innerCheck(settings, owner, definition, value);
87      }
88  
89      /** The method all subclasses should implement to do the actual checking.
90       *
91       * @param owner the ComplexType owning the attribute to check.
92       * @param definition the definition to check the attribute against.
93       * @param value the value to check.
94       * @return null if ok, or an instance of {@link FailedCheck}if the check
95       *         failed.
96       */
97      public abstract FailedCheck innerCheck(CrawlerSettings settings,
98              ComplexType owner, Type definition, Object   value);
99  
100     /** Get the default message to return if a check fails.
101      *
102      * @return the default message to return if a check fails.
103      */
104     protected String   getDefaultMessage() {
105         return msg;
106     }
107 
108     /** Objects of this class represents failed constraint checks.
109      *
110      * @author John Erik Halse
111      */
112     public class FailedCheck {
113         private final String   msg;
114         private final CrawlerSettings settings;
115         private final ComplexType owner;
116         private final Type definition;
117         private final Object   value;
118         protected final ArrayList  <Object  > messageArguments
119          = new ArrayList  <Object  >();
120 
121         /**
122          * Construct a new FailedCheck object.
123          *
124          * @param settings the CrawlerSettings object for which this check was
125          *            executed.
126          * @param owner the ComplexType owning the attribute to check.
127          * @param definition the definition to check the attribute against.
128          * @param value the value to check.
129          * @param msg a message describing what went wrong and possibly hints to
130          *            the user on how to fix it.
131          */
132         public FailedCheck(CrawlerSettings settings, ComplexType owner,
133                 Type definition, Object   value, String   msg) {
134             this.msg = msg;
135             this.settings = settings;
136             this.owner = owner;
137             this.definition = definition;
138             this.value = value;
139             this.messageArguments.add(definition.getName());
140             this.messageArguments.add(value);
141             this.messageArguments.add(owner.getName());
142         }
143 
144         /**
145          * Construct a new FailedCheck object using the constraints default
146          * message.
147          *
148          * @param settings the CrawlerSettings object for which this check was
149          *            executed.
150          * @param owner the ComplexType owning the attribute to check.
151          * @param definition the definition to check the attribute against.
152          * @param value the value to check.
153          */
154         public FailedCheck(CrawlerSettings settings, ComplexType owner,
155                 Type definition, Object   value) {
156             this(settings, owner, definition, value, getDefaultMessage());
157         }
158 
159         /** Get the error message.
160          *
161          * @return the error message.
162          */
163         public String   getMessage() {
164             return MessageFormat.format(msg, messageArguments.toArray());
165         }
166 
167         /** Get the severity level.
168          *
169          * @return the severity level.
170          */
171         public Level   getLevel() {
172             return severity;
173         }
174 
175         /** Get the definition for the checked attribute.
176          *
177          * @return the definition for the checked attribute.
178          */
179         public Type getDefinition() {
180             return definition;
181         }
182 
183         /** Get the value of the checked attribute.
184          *
185          * @return the value of the checked attribute.
186          */
187         public Object   getValue() {
188             return value;
189         }
190 
191         /** Get the {@link ComplexType} owning the checked attribute.
192          *
193          * @return the {@link ComplexType} owning the checked attribute.
194          */
195         public ComplexType getOwner() {
196             return owner;
197         }
198 
199         /** Get the {@link CrawlerSettings} for the checked attribute.
200          *
201          * @return the {@link CrawlerSettings} for the checked attribute.
202          */
203         public CrawlerSettings getSettings() {
204             return settings;
205         }
206 
207         /** Returns a human readeable string for the failed check.
208          * Returns the same as {@link #getMessage()}
209          *
210          * @return A human readeable string for the failed check.
211          */
212         public String   toString() {
213             return getMessage();
214         }
215     }
216 
217     /** Compare this constraints level to another constraint.
218      * This method is implemented to let constraints be sorted with the highest
219      * level first.
220      *
221      * @param o a Constraint to compare to.
222      */
223     public int compareTo(Constraint o) {
224         Constraint c = (Constraint) o;
225         return c.severity.intValue() - severity.intValue();
226     }
227 
228 }
229
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags