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_PERMISSIONS = "process_permissions"
77 .intern();
78
79 public final static String KEY_PROCESS_USER_PREFERENCES = "process_user_preferences"
80 .intern();
81 public final static String KEY_PROCESS_PORTAL_PREFERENCES = "process_portal_preferences"
82 .intern();
83
84 public final static String KEY_OVERWRITE_EXISTING = "overwrite_existing"
85 .intern();
86
87 public final static String KEY_BACKUP_BEFORE_PROCESS = "backup_before_process"
88 .intern();
89
90 /*** export/import instructions secondary*/
91 public final static String KEY_PROCESS_ENTITIES = "process_entities".intern();
92 public final static String KEY_PROCESS_PREFERENCES = "process_preferences".intern();
93
94
95
96 /***<p> the main tag in the XML file */
97 public final static String TAG_SNAPSHOT = "Snapshot";
98 public final static String TAG_SECONDARYSNAPSHOT = "SecondaryData";
99
100 /***
101 * hand the serializer an existing component manager to access the
102 * environment
103 *
104 * @param cm
105 */
106 public void setComponentManager(ComponentManager cm)
107 throws SerializerException;
108
109 /***
110 * Create a component manager with the list of primary components (boot),
111 * the application components and the root path of the application
112 *
113 * @param appRoot
114 * working directory
115 * @param bootConfig
116 * boot (primary) file or files (wildcards are allowed)
117 * @param appConfig
118 * application (secondary) file or files (wildcards are allowed)
119 * @return a newly initiated component manager
120 * @throws SerializerException
121 */
122 public void initializeComponentManager(String appRoot, String[] bootConfig,
123 String[] appConfig) throws SerializerException;
124
125 /***
126 * Main routine to export the set of data elements and write them to the
127 * named XML file. The default behavior of the serializer is that all
128 * available data is extracted and the target file gets created or
129 * overwritten
130 * <p>
131 * The caller can adjust the default behavior by passign in a map of flags.
132 * Each map entry is keyed by a key Constant and the associated Boolean
133 * value, for exammple KEY_PROCESS_USER_PREFERENCES, Boolean.FALSE would
134 * cause the serializer to skip user preferences.
135 * <p>
136 * Note that ProfilingRules require the users . Hence turning off User
137 * collection will automatically turn off the Profiling rules
138 *
139 *
140 * @param name
141 * of the snapshot
142 * @param exportFileName
143 * @param settings
144 * optional Map overwriting default export behavior
145 */
146 public void exportData(String name, String exportFileName, Map settings)
147 throws SerializerException;
148
149 /***
150 * Main routine to import the set of data elements and write them to the
151 * current environment. The default behavior of the serializer is that all
152 * available data is read and written to the current environment.
153 * <p>
154 * Existing entries (like users) etc. will be overwritten with the provided
155 * data.
156 * <p>
157 * The caller can adjust the default behavior by passign in a map of flags.
158 * Each map entry is keyed by a key Constant and the associated Boolean
159 * value, for exammple KEY_PROCESS_USER_PREFERENCES, Boolean.FALSE would
160 * cause the serializer to skip user preferences.
161 * <p>
162 * Note that settings are valid throughout each invocation. Therefore if a
163 * caller wants to preserve current users and only add new entries while at
164 * the same time overwrite all profiling rules, exportData has to be invoked
165 * twice - once to process only the users with the no-overwrite option and
166 * once to process the profiling rules
167 *
168 * @param importFileName
169 * @param settings
170 * optional Map overwriting default import behavior
171 * @return
172 */
173 public void importData(String importFileName, Map settings)
174 throws SerializerException;
175
176 /***
177 * Set the default indent for the XML output
178 *
179 * @param indent
180 */
181 public void setDefaultIndent(String indent);
182
183 /***
184 * Get the current indent setting for XML files
185 *
186 * @return the current indent setting
187 */
188 public String getDefaultIndent();
189
190 /***
191 * release the resources etc.
192 *
193 */
194 public void closeUp();
195
196 }