001: /**
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */package org.apache.jetspeed.serializer;
017:
018: import java.util.Map;
019:
020: import org.apache.jetspeed.components.ComponentManager;
021:
022: /**
023: * Jetspeed Serializer
024: * <p>
025: * The Serializer is capable of reading and writing the current content of the
026: * Jetspeed environment to and from XML files. The component can be used from a
027: * standalone java application for seeding a new database or from a running
028: * portal as an administrative backup/restore function.
029: * <p>
030: * The XML file needs to indicate whether passwords used in credentials
031: * are plain text or whether they are encoded. The import algoritm can determine -
032: * prior to reading users - which encode/decode scheme was used and if <none> or
033: * <implements PasswordEncodingService> then we store plain passwords (Note that
034: * that alone requires the resulting XML to be encoded!!!!!)
035: *
036: * @author <a href="mailto:hajo@bluesunrise.com">Hajo Birthelmer</a>
037: * @version $Id: JetspeedSerializer.java 0 2006-10-31 22:51:28Z hjb $
038: *
039: */
040: public interface JetspeedSerializer {
041:
042: /** Password handling */
043: /** Error in determening correct password handling */
044: public final static short ERROR_DECODING = -1;
045:
046: /** the passwords are in clear text */
047: public final static short NO_DECODING = 0;
048:
049: /**
050: * the passwords are encoded and the provider is the same as the data
051: * source, but is a 1-way algorithm
052: */
053: public final static short PASSTHRU_REQUIRED = 1;
054:
055: /**
056: * the passwords are encoded and the provider is the same as the data source
057: * and we have a 2-way algorithm
058: */
059: public final static short DECODING_SUPPORTED = 2;
060:
061: /** the passwords are encoded and the current provider is DIFFERENT.... */
062: public final static short INVALID_PASSWORDS = 3;
063:
064: /** export/import instructions */
065:
066: public final static String KEY_PROCESS_USERS = "process_users"
067: .intern();
068:
069: public final static String KEY_PROCESS_CAPABILITIES = "process_capabilities"
070: .intern();
071:
072: public final static String KEY_PROCESS_PROFILER = "process_profiler"
073: .intern();
074:
075: public final static String KEY_PROCESS_PERMISSIONS = "process_permissions"
076: .intern();
077:
078: public final static String KEY_PROCESS_USER_PREFERENCES = "process_user_preferences"
079: .intern();
080: public final static String KEY_PROCESS_PORTAL_PREFERENCES = "process_portal_preferences"
081: .intern();
082:
083: public final static String KEY_OVERWRITE_EXISTING = "overwrite_existing"
084: .intern();
085:
086: public final static String KEY_BACKUP_BEFORE_PROCESS = "backup_before_process"
087: .intern();
088:
089: /** export/import instructions secondary*/
090: public final static String KEY_PROCESS_ENTITIES = "process_entities"
091: .intern();
092: public final static String KEY_PROCESS_PREFERENCES = "process_preferences"
093: .intern();
094:
095: /**<p> the main tag in the XML file */
096: public final static String TAG_SNAPSHOT = "Snapshot";
097: public final static String TAG_SECONDARYSNAPSHOT = "SecondaryData";
098:
099: /**
100: * hand the serializer an existing component manager to access the
101: * environment
102: *
103: * @param cm
104: */
105: public void setComponentManager(ComponentManager cm)
106: throws SerializerException;
107:
108: /**
109: * Create a component manager with the list of primary components (boot),
110: * the application components and the root path of the application
111: *
112: * @param appRoot
113: * working directory
114: * @param bootConfig
115: * boot (primary) file or files (wildcards are allowed)
116: * @param appConfig
117: * application (secondary) file or files (wildcards are allowed)
118: * @return a newly initiated component manager
119: * @throws SerializerException
120: */
121: public void initializeComponentManager(String appRoot,
122: String[] bootConfig, String[] appConfig)
123: 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,
147: Map settings) 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: }
|