AbstractPatch


1   /*
2    * Copyright (C) 2005 Alfresco, Inc.
3    *
4    * Licensed under the Mozilla Public License version 1.1 
5    * with a permitted attribution clause. You may obtain a
6    * copy of the License at
7    *
8    *   http://www.alfresco.org/legal/license.txt
9    *
10   * Unless required by applicable law or agreed to in writing,
11   * software distributed under the License is distributed on an
12   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
13   * either express or implied. See the License for the specific
14   * language governing permissions and limitations under the
15   * License.
16   */
17  package org.alfresco.repo.admin.patch;
18  
19  import java.io.PrintWriter  ;
20  import java.io.StringWriter  ;
21  import java.util.Collections  ;
22  import java.util.List  ;
23  
24  import org.alfresco.error.AlfrescoRuntimeException;
25  import org.alfresco.repo.transaction.TransactionUtil;
26  import org.alfresco.repo.transaction.TransactionUtil.TransactionWork;
27  import org.alfresco.service.cmr.admin.PatchException;
28  import org.alfresco.service.transaction.TransactionService;
29  import org.apache.commons.logging.Log;
30  import org.apache.commons.logging.LogFactory;
31  
32  /**
33   * Base implementation of the patch.  This class ensures that the patch is
34   * thread- and transaction-safe.
35   * 
36   * @author Derek Hulley
37   */
38  public abstract class AbstractPatch implements Patch
39  {
40      /**
41       * I18N message when properties nto set.
42       * <ul>
43       *   <li>{0} = property name</li>
44       *   <li>{1} = patch instance</li>
45       * </ul>
46       */
47      public static final String   ERR_PROPERTY_NOT_SET = "patch.general.property_not_set";
48      
49      private static Log logger = LogFactory.getLog(AbstractPatch.class);
50      
51      private String   id;
52      private int fixesFromSchema;
53      private int fixesToSchema;
54      private int targetSchema;
55      private String   description;
56      /** a list of patches that this one depends on */
57      private List  <Patch> dependsOn;
58      /** flag indicating if the patch was successfully applied */
59      private boolean applied;
60      /** the service to register ourselves with */
61      private PatchService patchService;
62      private TransactionService transactionService;
63  
64      public AbstractPatch()
65      {
66          this.fixesFromSchema = -1;
67          this.fixesToSchema = -1;
68          this.targetSchema = -1;
69          this.applied = false;
70          this.dependsOn = Collections.emptyList();
71      }
72      
73      @Override  
74      public String   toString()
75      {
76          StringBuilder   sb = new StringBuilder  (256);
77          sb.append("Patch")
78            .append("[ id=").append(id)
79            .append(", description=").append(description)
80            .append(", fixesFromSchema=").append(fixesFromSchema)
81            .append(", fixesToSchema=").append(fixesToSchema)
82            .append(", targetSchema=").append(targetSchema)
83            .append("]");
84          return sb.toString();
85      }
86  
87      /**
88       * Set the service that this patch will register with for execution.
89       */
90      public void setPatchService(PatchService patchService)
91      {
92          this.patchService = patchService;
93      }
94  
95      /**
96       * Set the transaction provider so that each execution can be performed within a transaction
97       */
98      public void setTransactionService(TransactionService transactionService)
99      {
100         this.transactionService = transactionService;
101     }
102 
103     /**
104      * This ensures that this bean gets registered with the appropriate {@link PatchService service}. 
105      */
106     public void init()
107     {
108         if (patchService == null)
109         {
110             throw new AlfrescoRuntimeException("Mandatory property not set: patchService");
111         }
112         patchService.registerPatch(this);
113     }
114 
115     public String   getId()
116     {
117         return id;
118     }
119 
120     /**
121      * 
122      * @param id the unique ID of the patch.  This dictates the order in which patches are applied.
123      */
124     public void setId(String   id)
125     {
126         this.id = id;
127     }
128 
129     public int getFixesFromSchema()
130     {
131         return fixesFromSchema;
132     }
133 
134     /**
135      * Set the smallest schema number that this patch may be applied to.
136      * 
137      * @param version a schema number not smaller than 0
138      */
139     public void setFixesFromSchema(int version)
140     {
141         if (version < 0)
142         {
143             throw new IllegalArgumentException  ("The 'fixesFromSchema' property may not be less than 0");
144         }
145         this.fixesFromSchema = version;
146         // auto-adjust the to version
147         if (fixesToSchema < fixesFromSchema)
148         {
149             setFixesToSchema(this.fixesFromSchema);
150         }
151     }
152 
153     public int getFixesToSchema()
154     {
155         return fixesToSchema;
156     }
157 
158     /**
159      * Set the largest schema version number that this patch may be applied to.
160      * 
161      * @param version a schema version number not smaller than the
162      *      {@link #setFixesFromSchema(int) from version} number.
163      */
164     public void setFixesToSchema(int version)
165     {
166         if (version < fixesFromSchema)
167         {
168             throw new IllegalArgumentException  ("'fixesToSchema' must be greater than or equal to 'fixesFromSchema'");
169         }
170         this.fixesToSchema = version;
171     }
172 
173     public int getTargetSchema()
174     {
175         return targetSchema;
176     }
177 
178     /**
179      * Set the schema version that this patch attempts to take the existing schema to.
180      * This is for informational purposes only, acting as an indicator of intention rather
181      * than having any specific effect.
182      * 
183      * @param version a schema version number that must be greater than the
184      *      {@link #fixesToSchema max fix schema number}
185      */
186     public void setTargetSchema(int version)
187     {
188         if (version <= fixesToSchema)
189         {
190             throw new IllegalArgumentException  ("'targetSchema' must be greater than 'fixesToSchema'");
191         }
192         this.targetSchema = version;
193     }
194 
195     public String   getDescription()
196     {
197         return description;
198     }
199 
200     /**
201      * @param description a thorough description of the patch
202      */
203     public void setDescription(String   description)
204     {
205         this.description = description;
206     }
207 
208     public List  <Patch> getDependsOn()
209     {
210         return this.dependsOn;
211     }
212     /**
213      * Set all the dependencies for this patch.  It should not be executed
214      * before all the dependencies have been applied.
215      * 
216      * @param dependsOn a list of dependencies
217      */
218     public void setDependsOn(List  <Patch> dependsOn)
219     {
220         this.dependsOn = dependsOn;
221     }
222 
223     public boolean applies(int version)
224     {
225         return ((this.fixesFromSchema <= version) && (version <= fixesToSchema));
226     }
227     
228     /**
229      * Performs a null check on the supplied value.
230      * 
231      * @param value value to check
232      * @param name name of the property to report
233      */
234     protected final void checkPropertyNotNull(Object   value, String   name)
235     {
236         if (value == null)
237         {
238             throw new PatchException(ERR_PROPERTY_NOT_SET, "bootstrapView", this);
239         }
240     }
241 
242     /**
243      * Check that the schema version properties have been set appropriately.
244      * Derived classes can override this method to perform their own validation provided
245      * that this method is called by the derived class.
246      */
247     protected void checkProperties()
248     {
249         // check that the necessary properties have been set
250         checkPropertyNotNull(id, "id");
251         checkPropertyNotNull(description, "description");
252         checkPropertyNotNull(transactionService, "transactionService");
253         if (fixesFromSchema == -1 || fixesToSchema == -1 || targetSchema == -1)
254         {
255             throw new AlfrescoRuntimeException(
256                     "Patch properties 'fixesFromSchema', 'fixesToSchema' and 'targetSchema' have not all been set on this patch: \n" +
257                     "   patch: " + this);
258         }
259     }
260     
261     /**
262      * Sets up the transaction and ensures thread-safety.
263      * 
264      * @see #applyInternal()
265      */
266     public synchronized String   apply() throws PatchException
267     {
268         // ensure that this has not been executed already
269         if (applied)
270         {
271             throw new AlfrescoRuntimeException("The patch has already been executed: \n" +
272                     "   patch: " + this);
273         }
274         // check properties
275         checkProperties();
276         // execute in a transaction
277         try
278         {
279             TransactionWork<String  > patchWork = new TransactionWork<String  >()
280             {
281                 public String   doWork() throws Exception  
282                 {
283                     String   report = applyInternal();
284                     // done
285                     return report;
286                 };
287             };
288             String   report = TransactionUtil.executeInNonPropagatingUserTransaction(transactionService, patchWork);
289             // the patch was successfully applied
290             applied = true;
291             // done
292             if (logger.isDebugEnabled())
293             {
294                 logger.debug("Patch successfully applied: \n" +
295                         "   patch: " + this + "\n" +
296                         "   report: " + report);
297             }
298             return report;
299         }
300         catch (PatchException e)
301         {
302             // no need to extract the exception
303             throw e;
304         }
305         catch (Throwable   e)
306         {
307             // check whether there is an embedded patch exception
308             Throwable   cause = e.getCause();
309             if (cause != null && cause instanceof PatchException)
310             {
311                 throw (PatchException) cause;
312             }
313             // need to generate a message from the exception
314             String   report = makeReport(e);
315             // generate the correct exception
316             throw new PatchException(report);
317         }
318     }
319     
320     /**
321      * Dumps the error's full message and trace to the String
322      * 
323      * @param e the throwable
324      * @return Returns a String representative of the printStackTrace method
325      */
326     private String   makeReport(Throwable   e)
327     {
328         StringWriter   stringWriter = new StringWriter  (1024);
329         PrintWriter   printWriter = new PrintWriter  (stringWriter, true);
330         try
331         {
332             e.printStackTrace(printWriter);
333             return stringWriter.toString();
334         }
335         finally
336         {
337             printWriter.close();
338         }
339     }
340 
341     /**
342      * This method does the work.  All transactions and thread-safety will be taken care of by this class.
343      * Any exception will result in the transaction being rolled back.
344      * 
345      * @return Returns the report (only success messages).
346      * @see #apply()
347      * @throws Exception anything can be thrown.  This must be used for all failures.
348      */
349     protected abstract String   applyInternal() throws Exception  ;
350 }
351
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags