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 }