View Javadoc

1   /*
2    * Copyright 2003,2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  /*
17   * This source code implements specifications defined by the Java
18   * Community Process. In order to remain compliant with the specification
19   * DO NOT add / change / or delete method signatures!
20   */
21  package javax.portlet;
22  
23  /***
24   * The portlet should throw the <CODE>UnavailableException</CODE> when 
25   * the portlet is either temporarily or permanently unavailable to handle requests.
26   *
27   **/
28  
29  public class UnavailableException extends PortletException
30  {
31  
32  
33      private boolean     permanent;         // needs admin action?
34      private int         seconds;           // unavailability estimate
35  
36  
37      /***
38       * 
39       * Constructs a new exception with a descriptive
40       * message indicating that the portlet is permanently
41       * unavailable.
42       *
43       * @param text 	a <code>String</code> specifying the
44       *                  descriptive message
45       *
46       */
47  
48      public UnavailableException(String text) {
49  	super(text);
50  
51  	permanent = true;
52      }
53  
54      /***
55       * Constructs a new exception with a descriptive message
56       * indicating that the portlet is temporarily unavailable
57       * and giving an estimate of how long it will be unavailable.
58       * 
59       * <p>In some cases, the portlet cannot make an estimate. For
60       * example, the portlet might know that a server it needs is
61       * not running, but it might not be able to report how long it will take
62       * to be restored to functionality. This can be indicated with
63       * a negative or zero value for the <code>seconds</code> argument.
64       *
65       * @param text	a <code>String</code> specifying the
66       *                  descriptive message. This message can be written
67       *                  to a log file or displayed for the user.
68       *
69       * @param seconds	an integer specifying the number of seconds
70       * 			for which the portlet expects to be unavailable; if
71       *			this is zero or negative, it indicates that the portlet
72       *			cannot make an estimate.
73       *
74       */
75      
76      public UnavailableException(String text, int seconds) {
77  	super(text);
78  
79  	if (seconds <= 0)
80  	    this.seconds = -1;
81  	else
82  	    this.seconds = seconds;
83  
84  	permanent = false;
85      }
86  
87      /***
88       *
89       * Returns a <code>boolean</code> indicating
90       * whether the portlet is permanently unavailable.
91       * If so, something is wrong with the portlet, and the
92       * system administrator must take some corrective action.
93       *
94       * @return		<code>true</code> if the portlet is
95       *			permanently unavailable; <code>false</code>
96       *			if the portlet is temporarily
97       *			unavailable.
98       *
99       */
100      
101     public boolean isPermanent() {
102 	return permanent;
103     }
104   
105 
106     /***
107      * Returns the time in seconds for which the portlet can be expected to 
108      * be unavailable.  
109      * <p>
110      * If the portlet is called again while it is still unavailable, it
111      * indicates the same time estimate. No effort is
112      * made to correct for the time elapsed since the exception was
113      * first reported.
114      * <p>
115      * If this method returns zero or a negative number, the portlet
116      * is permanently unavailable or cannot provide an estimate of
117      * how long it will be unavailable. 
118      *
119      * @return		an integer specifying the number of seconds
120      *			the portlet will be temporarily unavailable,
121      *			or zero or a negative number if the portlet is permanently
122      *			unavailable or cannot make an estimate.
123      *
124      */
125      
126     public int getUnavailableSeconds() {
127 	return permanent ? -1 : seconds;
128     }
129 
130 
131 }