001/*
002 * Copyright (c) 2010-2024 Mark Allen, Norbert Bartels.
003 *
004 * Permission is hereby granted, free of charge, to any person obtaining a copy
005 * of this software and associated documentation files (the "Software"), to deal
006 * in the Software without restriction, including without limitation the rights
007 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
008 * copies of the Software, and to permit persons to whom the Software is
009 * furnished to do so, subject to the following conditions:
010 *
011 * The above copyright notice and this permission notice shall be included in
012 * all copies or substantial portions of the Software.
013 *
014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
015 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
016 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
017 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
018 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
019 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
020 * THE SOFTWARE.
021 */
022package com.restfb;
023
024import static java.lang.annotation.ElementType.METHOD;
025import static java.lang.annotation.RetentionPolicy.RUNTIME;
026
027import java.lang.annotation.Retention;
028import java.lang.annotation.Target;
029import java.util.List;
030
031import com.restfb.exception.FacebookJsonMappingException;
032
033/**
034 * Specifies how a Facebook JSON-to-Java (and vice-versa) mapper must operate.
035 * <p>
036 * Note that implementors must be able to handle illegal JSON in {@link #toJavaObject(String, Class)} and
037 * {@link #toJavaList(String, Class)} in order to correctly process Facebook responses. For example, the
038 * {@code Users.getLoggedInUser} Legacy API call returns a value like {@code 1240077}, which is not valid JSON.
039 * 
040 * @author <a href="http://restfb.com">Mark Allen</a>
041 */
042public interface JsonMapper {
043  /**
044   * Given a JSON string, create and return a new instance of a corresponding Java object of type {@code type}.
045   * <p>
046   * The Java {@code type} must have a no-argument constructor.
047   * 
048   * @param <T>
049   *          Java type to map to.
050   * @param json
051   *          The JSON to be mapped to a Java type.
052   * @param type
053   *          Java type token.
054   * @return A Java object (of type {@code type}) representation of the JSON input.
055   * @throws FacebookJsonMappingException
056   *           If an error occurs while mapping JSON to Java.
057   */
058  <T> T toJavaObject(String json, Class<T> type);
059
060  /**
061   * Given a JSON string, create and return a new instance of a corresponding Java {@link java.util.List} which contains
062   * elements of type {@code type}.
063   * <p>
064   * The Java {@code type} must have a no-argument constructor.
065   * 
066   * @param <T>
067   *          Java type to map to for each element of the list.
068   * @param json
069   *          The JSON to be mapped to a Java type.
070   * @param type
071   *          Java type token.
072   * @return A Java object (of type {@code List} which contains elements of type {@code type}) representation of the
073   *         JSON input.
074   * @throws FacebookJsonMappingException
075   *           If an error occurs while mapping JSON to Java.
076   */
077  <T> List<T> toJavaList(String json, Class<T> type);
078
079  /**
080   * Given a Java {@code object}, create and return a JSON string that represents it.
081   * <p>
082   * The {@code object}'s properties will be traversed recursively, allowing for arbitrarily complex JSON generation.
083   * 
084   * @param object
085   *          The Java object to map to JSON. Can be a Javabean, {@link java.util.List}, or {@link java.util.Map}.
086   * @return A JSON string.
087   * @throws FacebookJsonMappingException
088   *           If an error occurs while mapping Java to JSON.
089   * @since 1.4
090   */
091  String toJson(Object object);
092
093  /**
094   * Given a Java {@code object}, create and return a JSON string that represents it.
095   * <p>
096   * The {@code object}'s properties will be traversed recursively, allowing for arbitrarily complex JSON generation.
097   * 
098   * @param object
099   *          The Java object to map to JSON. Can be a Javabean, {@link java.util.List}, or {@link java.util.Map}.
100   * @param ignoreNullValuedProperties
101   *          If {@code true}, no Javabean properties with {@code null} values will be included in the generated JSON.
102   * @return A JSON string.
103   * @throws FacebookJsonMappingException
104   *           If an error occurs while mapping Java to JSON.
105   * @since 1.6.5
106   */
107  String toJson(Object object, boolean ignoreNullValuedProperties);
108
109  /**
110   * adds a {@link FacebookClient} implementation to the mapper.
111   *
112   * This is especially useful for mapping json to Connection objects that need the client itself.
113   * 
114   * @param facebookClient
115   *          that is used for Connection objects
116   */
117  void setFacebookClient(FacebookClient facebookClient);
118
119  /**
120   * If you apply this annotation to a method of a type mapped by {@code JsonMapper}, it will be called after the
121   * mapping operation has been completed.
122   * <p>
123   * The method you specify must take 0 parameters or a single {@code JsonMapper} parameter. Any other signature will
124   * cause a {@code FacebookJsonMappingException} to be thrown.
125   * <p>
126   * This is useful if you'd like to perform a custom post-mapping task, like massaging the data Facebook returns or
127   * custom mapping of fields {@code JsonMapper} isn't equipped to handle yet.
128   * 
129   * @author <a href="http://restfb.com">Mark Allen</a>
130   * @since 1.6.11
131   */
132  @Target({ METHOD })
133  @Retention(RUNTIME)
134  @interface JsonMappingCompleted {
135    // annotation
136  }
137}