| /* |
| * Copyright (c) OSGi Alliance (2017). All Rights Reserved. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.apache.felix.serializer; |
| |
| import java.util.Comparator; |
| import java.util.List; |
| import java.util.Map; |
| |
| import org.osgi.annotation.versioning.ProviderType; |
| import org.osgi.util.converter.Converter; |
| |
| /** |
| * A factory to create a writer with the desired behaviour. |
| * |
| * @author $Id:$ |
| */ |
| @ProviderType |
| public interface WriterFactory { |
| |
| /** |
| * A default Writer, but which will use a custom Converter. |
| * |
| * @param c the custom Converter that will be used by the Writer |
| * @return a default Writer, but one which will use a custom Converter |
| */ |
| Writer newDefaultWriter(Converter c); |
| |
| /** |
| * A writer that is useful for debugging. This write outputs "pretty" |
| * format. |
| * |
| * @param c the custom Converter that will be used by the Writer |
| * @return A new writer useful for debugging |
| */ |
| Writer newDebugWriter(Converter c); |
| |
| /** |
| * Register an ordering rule for this writer. |
| * |
| * An ordering rule causes the written json to be output in the order |
| * specified. This can be useful, for example, for debugging or when |
| * the data otherwise needs to be human consumable. |
| * |
| * This rule only affects map-type objects located at the given path. |
| * |
| * @param path the path where the key is located in the object graph. |
| * @param keyOrder A list with the desired key order. |
| * @return This factory object to allow further invocations on it. |
| */ |
| WriterFactory orderMap(String path, List<String> keyOrder); |
| |
| /** |
| * Register multiple ordering rules for this writer. |
| * |
| * An ordering rule causes the written json to be output in the order |
| * specified. This can be useful, for example, for debugging or when |
| * the data otherwise needs to be human consumable. |
| * |
| * This rule only affects map-type objects located at the given path. |
| * |
| * Each map entry is a path/keyOrder pair, the same as if calling |
| * WriterFactory.orderMap(String,List<String>). |
| * |
| * @param orderingRules the rules to be added |
| * @return This factory object to allow further invocations on it. |
| */ |
| WriterFactory orderMap( Map<String, List<String>> orderingRules ); |
| |
| /** |
| * Register an ordering rule for this writer. |
| * |
| * An ordering rule causes the written json to be output in the order |
| * specified. This can be useful, for example, for debugging or when |
| * the data otherwise needs to be human consumable. |
| * |
| * This rule only affects array-type objects located at the given path. |
| * |
| * @param path the path where the key is located in the object graph. |
| * @return This factory object to allow further invocations on it. |
| */ |
| WriterFactory orderArray(String path); |
| |
| /** |
| * Register an ordering rule for this writer. |
| * |
| * An ordering rule causes the written json to be output in the order |
| * specified. This can be useful, for example, for debugging or when |
| * the data otherwise needs to be human consumable. |
| * |
| * This rule only affects array-type objects located at the given path. |
| * |
| * @param path the path where the key is located in the object graph. |
| * @param comparator A comparator that will be used to sort the items in the array. |
| * @return This factory object to allow further invocations on it. |
| */ |
| WriterFactory orderArray(String path, Comparator<?> comparator); |
| |
| /** |
| * A convenience means of obtaining a JsonWriterFactory without having to |
| * configure service settings. |
| */ |
| static interface JsonWriterFactory extends WriterFactory {} |
| |
| /** |
| * A convenience means of obtaining a YamlWriterFactory without having to |
| * configure service settings. |
| */ |
| static interface YamlWriterFactory extends WriterFactory {} |
| } |