View Javadoc

1   /***
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.jetspeed.serializer;
18  
19  import java.util.Map;
20  
21  import org.apache.jetspeed.components.ComponentManager;
22  
23  /***
24   * Jetspeed Serializer
25   * <p>
26   * The Serializer is capable of reading and writing the current content of the
27   * Jetspeed environment to and from XML files. The component can be used from a
28   * standalone java application for seeding a new database or from a running
29   * portal as an administrative backup/restore function.
30   * <p>
31   * The XML file needs to indicate whether passwords used in credentials
32   * are plain text or whether they are encoded. The import algoritm can determine -
33   * prior to reading users - which encode/decode scheme was used and if <none> or
34   * <implements PasswordEncodingService> then we store plain passwords (Note that
35   * that alone requires the resulting XML to be encoded!!!!!)
36   * 
37   * @author <a href="mailto:hajo@bluesunrise.com">Hajo Birthelmer</a>
38   * @version $Id: JetspeedSerializer.java 0 2006-10-31 22:51:28Z hjb $
39   * 
40   */
41  public interface JetspeedSerializer
42  {
43  
44      /*** Password handling */
45      /*** Error in determening correct password handling */
46      public final static short ERROR_DECODING = -1;
47  
48      /*** the passwords are in clear text */
49      public final static short NO_DECODING = 0;
50  
51      /***
52       * the passwords are encoded and the provider is the same as the data
53       * source, but is a 1-way algorithm
54       */
55      public final static short PASSTHRU_REQUIRED = 1;
56  
57      /***
58       * the passwords are encoded and the provider is the same as the data source
59       * and we have a 2-way algorithm
60       */
61      public final static short DECODING_SUPPORTED = 2;
62  
63      /*** the passwords are encoded and the current provider is DIFFERENT.... */
64      public final static short INVALID_PASSWORDS = 3;
65  
66      /*** export/import instructions */
67  
68      public final static String KEY_PROCESS_USERS = "process_users".intern();
69  
70      public final static String KEY_PROCESS_CAPABILITIES = "process_capabilities"
71              .intern();
72  
73      public final static String KEY_PROCESS_PROFILER = "process_profiler"
74              .intern();
75  
76      public final static String KEY_PROCESS_USER_PREFERENCES = "process_user_preferences"
77              .intern();
78      public final static String KEY_PROCESS_PORTAL_PREFERENCES = "process_portal_preferences"
79          .intern();
80  
81      public final static String KEY_OVERWRITE_EXISTING = "overwrite_existing"
82              .intern();
83  
84      public final static String KEY_BACKUP_BEFORE_PROCESS = "backup_before_process"
85              .intern();
86  
87      /*** export/import instructions secondary*/
88      public final static String KEY_PROCESS_ENTITIES = "process_entities".intern();
89      public final static String KEY_PROCESS_PREFERENCES = "process_preferences".intern();
90      
91      
92      
93      /***<p> the main tag in the XML file */
94      public final static String TAG_SNAPSHOT = "Snapshot"; 
95      public final static String TAG_SECONDARYSNAPSHOT = "SecondaryData"; 
96      
97      /***
98       * hand the serializer an existing component manager to access the
99       * environment
100      * 
101      * @param cm
102      */
103     public void setComponentManager(ComponentManager cm)
104             throws SerializerException;
105 
106     /***
107      * Create a component manager with the list of primary components (boot),
108      * the application components and the root path of the application
109      * 
110      * @param appRoot
111      *            working directory
112      * @param bootConfig
113      *            boot (primary) file or files (wildcards are allowed)
114      * @param appConfig
115      *            application (secondary) file or files (wildcards are allowed)
116      * @return a newly initiated component manager
117      * @throws SerializerException
118      */
119     public void initializeComponentManager(String appRoot, String[] bootConfig,
120             String[] appConfig) throws SerializerException;
121 
122     /***
123      * Main routine to export the set of data elements and write them to the
124      * named XML file. The default behavior of the serializer is that all
125      * available data is extracted and the target file gets created or
126      * overwritten
127      * <p>
128      * The caller can adjust the default behavior by passign in a map of flags.
129      * Each map entry is keyed by a key Constant and the associated Boolean
130      * value, for exammple KEY_PROCESS_USER_PREFERENCES, Boolean.FALSE would
131      * cause the serializer to skip user preferences.
132      * <p>
133      * Note that ProfilingRules require the users . Hence turning off User
134      * collection will automatically turn off the Profiling rules
135      * 
136      * 
137      * @param name
138      *            of the snapshot
139      * @param exportFileName
140      * @param settings
141      *            optional Map overwriting default export behavior
142      */
143     public void exportData(String name, String exportFileName, Map settings)
144             throws SerializerException;
145 
146     /***
147      * Main routine to import the set of data elements and write them to the
148      * current environment. The default behavior of the serializer is that all
149      * available data is read and written to the current environment.
150      * <p>
151      * Existing entries (like users) etc. will be overwritten with the provided
152      * data.
153      * <p>
154      * The caller can adjust the default behavior by passign in a map of flags.
155      * Each map entry is keyed by a key Constant and the associated Boolean
156      * value, for exammple KEY_PROCESS_USER_PREFERENCES, Boolean.FALSE would
157      * cause the serializer to skip user preferences.
158      * <p>
159      * Note that settings are valid throughout each invocation. Therefore if a
160      * caller wants to preserve current users and only add new entries while at
161      * the same time overwrite all profiling rules, exportData has to be invoked
162      * twice - once to process only the users with the no-overwrite option and
163      * once to process the profiling rules
164      * 
165      * @param importFileName
166      * @param settings
167      *            optional Map overwriting default import behavior
168      * @return
169      */
170     public void importData(String importFileName, Map settings)
171             throws SerializerException;
172 
173     /***
174      * Set the default indent for the XML output
175      * 
176      * @param indent
177      */
178     public void setDefaultIndent(String indent);
179 
180     /***
181      * Get the current indent setting for XML files
182      * 
183      * @return the current indent setting
184      */
185     public String getDefaultIndent();
186 
187     /***
188      * reelase the resources etc.
189      * 
190      */
191     public void closeUp();
192 
193 }