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 */
017package org.apache.juneau.bean.jsonapi;
018
019import static org.apache.juneau.commons.utils.CollectionUtils.*;
020import static org.apache.juneau.commons.utils.Shorts.*;
021
022import java.util.*;
023
024import org.apache.juneau.marshall.*;
025import org.apache.juneau.marshall.marshaller.*;
026
027/**
028 * Represents a JSON:API Link Object as defined by
029 * <a href="https://jsonapi.org/format/#document-links">JSON:API v1.1 &#167; Links</a>.
030 *
031 * <p>
032 * Per the spec, each {@code links} entry may be either a JSON string URL or a JSON object with these members:
033 * {@code href} (required URI), {@code rel}, {@code describedby}, {@code title}, {@code type} (media-type hint),
034 * {@code hreflang} (language tag), and {@code meta}. The single-vs-object union is handled by
035 * {@link JsonApiLinkOrStringSwap}, applied via field-level {@code @BeanProp("links") @Swap(...)} on every type
036 * carrying a {@code links} map.
037 *
038 * <h5 class='section'>See Also:</h5><ul>
039 *   <li class='link'><a href="https://jsonapi.org/format/#document-links">JSON:API v1.1 &gt; Links</a>
040 *   <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanJsonApi">juneau-bean-jsonapi</a>
041 * </ul>
042 */
043@Marshalled
044public class JsonApiLink {
045
046   private String href;
047   private String rel;
048   private String describedby;
049   private String title;
050   private String type;
051   private String hreflang;
052   private Map<String,Object> meta;
053
054   /**
055    * Default constructor.
056    */
057   public JsonApiLink() {}
058
059   /**
060    * Convenience constructor with the required {@code href} field.
061    *
062    * @param href The link target URI.  Can be <jk>null</jk> to leave the property unset.
063    */
064   public JsonApiLink(String href) {
065      this.href = href;
066   }
067
068   /**
069    * Bean property getter:  <property>href</property>.
070    *
071    * @return The value of the <property>href</property> property, or <jk>null</jk> if it is not set.
072    */
073   public String getHref() { return href; }
074
075   /**
076    * Bean property setter:  <property>href</property>.
077    *
078    * @param value The new value for this property.  Can be <jk>null</jk> to unset the property.
079    * @return This object.
080    */
081   public JsonApiLink setHref(String value) {
082      href = value;
083      return this;
084   }
085
086   /**
087    * Bean property getter:  <property>rel</property>.
088    *
089    * @return The value of the <property>rel</property> property, or <jk>null</jk> if it is not set.
090    */
091   public String getRel() { return rel; }
092
093   /**
094    * Bean property setter:  <property>rel</property>.
095    *
096    * @param value The new value for this property.  Can be <jk>null</jk> to unset the property.
097    * @return This object.
098    */
099   public JsonApiLink setRel(String value) {
100      rel = value;
101      return this;
102   }
103
104   /**
105    * Bean property getter:  <property>describedby</property>.
106    *
107    * @return The value of the <property>describedby</property> property, or <jk>null</jk> if it is not set.
108    */
109   public String getDescribedby() { return describedby; }
110
111   /**
112    * Bean property setter:  <property>describedby</property>.
113    *
114    * @param value The new value for this property.  Can be <jk>null</jk> to unset the property.
115    * @return This object.
116    */
117   public JsonApiLink setDescribedby(String value) {
118      describedby = value;
119      return this;
120   }
121
122   /**
123    * Bean property getter:  <property>title</property>.
124    *
125    * @return The value of the <property>title</property> property, or <jk>null</jk> if it is not set.
126    */
127   public String getTitle() { return title; }
128
129   /**
130    * Bean property setter:  <property>title</property>.
131    *
132    * @param value The new value for this property.  Can be <jk>null</jk> to unset the property.
133    * @return This object.
134    */
135   public JsonApiLink setTitle(String value) {
136      title = value;
137      return this;
138   }
139
140   /**
141    * Bean property getter:  <property>type</property>.
142    *
143    * <p>
144    * Media-type hint for the target resource.
145    *
146    * @return The value of the <property>type</property> property, or <jk>null</jk> if it is not set.
147    */
148   public String getType() { return type; }
149
150   /**
151    * Bean property setter:  <property>type</property>.
152    *
153    * @param value The new value for this property.  Can be <jk>null</jk> to unset the property.
154    * @return This object.
155    */
156   public JsonApiLink setType(String value) {
157      type = value;
158      return this;
159   }
160
161   /**
162    * Bean property getter:  <property>hreflang</property>.
163    *
164    * @return The value of the <property>hreflang</property> property, or <jk>null</jk> if it is not set.
165    */
166   public String getHreflang() { return hreflang; }
167
168   /**
169    * Bean property setter:  <property>hreflang</property>.
170    *
171    * @param value The new value for this property.  Can be <jk>null</jk> to unset the property.
172    * @return This object.
173    */
174   public JsonApiLink setHreflang(String value) {
175      hreflang = value;
176      return this;
177   }
178
179   /**
180    * Bean property getter:  <property>meta</property>.
181    *
182    * @return The value of the <property>meta</property> property, or <jk>null</jk> if it is not set.
183    */
184   public Map<String,Object> getMeta() { return u(meta); }
185
186   /**
187    * Bean property setter:  <property>meta</property>.
188    *
189    * @param value The new value for this property.  Can be <jk>null</jk> to unset the property.
190    * @return This object.
191    */
192   public JsonApiLink setMeta(Map<String,Object> value) {
193      meta = value;
194      return this;
195   }
196
197   /**
198    * Convenience method to add a single meta entry.
199    *
200    * @param name The meta key.  Can be <jk>null</jk> ({@link LinkedHashMap} tolerates a <jk>null</jk> key).
201    * @param value The meta value.  Can be <jk>null</jk> (stored as <jk>null</jk>).
202    * @return This object.
203    */
204   public JsonApiLink putMeta(String name, Object value) {
205      if (meta == null)
206         meta = map();
207      meta.put(name, value);
208      return this;
209   }
210
211   @Override /* Overridden from Object */
212   public String toString() {
213      return Json.of(this);
214   }
215}