dev.dejvokep.boostedyaml.serialization.YamlSerializer Maven / Gradle / Ivy

Go to download
/*
 * Copyright 2024 https://dejvokep.dev/
 *
 * 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 dev.dejvokep.boostedyaml.serialization;

import dev.dejvokep.boostedyaml.block.Block;
import dev.dejvokep.boostedyaml.settings.general.GeneralSettings;
import dev.dejvokep.boostedyaml.utils.supplier.MapSupplier;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.util.Map;
import java.util.Set;

/**
 * Interface used by custom serializer implementations. If you are looking into building your own implementation, it is
 * recommended that you read the wiki.
 */
public interface YamlSerializer {

    /**
     * Attempts to deserialize the given map into a class instance using this serializer.
     * 
     * The given map is a raw object map - there are no {@link Block} instances, just the values themselves.
     * 

     * If the serializer does not recognize the map, or could not deserialize the map, this method must return
     * null.
     *
     * @param map the raw map to deserialize
     * @return the deserialized object
     */
    @Nullable
    Object deserialize(@NotNull Map map);

    /**
     * Attempts to serialize the given object into a map and returns it.
     * 

     * The given object is guaranteed to be:
     * 

     *     of type contained within {@link #getSupportedClasses()},
     *     a sub-class of any of {@link #getSupportedParentClasses()}.
     * 
     * Map supplier is provided to supply default map as configured in {@link GeneralSettings#getDefaultMapSupplier()}.
     * Serializers should not use their own map implementations, they should return the map provided by the supplier.
     * 
     * If could not serialize into a map, this method must return null.
     *
     * @param object   the object to serialize
     * @param supplier the supplier used to supply default maps
     * @param  type of the object to serialize
     * @return the serialized object
     */
    @Nullable
     Map serialize(@NotNull T object, @NotNull MapSupplier supplier);

    /**
     * Returns a set of all explicitly defined classes this serializer supports and can (de-)serialize.
     * 

     * The returned set cannot be null as indicated by the annotation.
     *
     * @return the set of supported classes
     */
    @NotNull
    Set> getSupportedClasses();

    /**
     * Returns a set of all parent classes (classes, interfaces...) instances of which this serializer supports and can
     * (de-)serialize.
     * 
     * The returned set cannot be null as indicated by the annotation.
     *
     * @return the set of supported parent classes
     */
    @NotNull
    Set> getSupportedParentClasses();

}