001/**
002 * Copyright 2014 Tampere University of Technology, Pori Department
003 * 
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 * 
008 *   http://www.apache.org/licenses/LICENSE-2.0
009 * 
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package service.tut.pori.contentanalysis;
017
018import javax.xml.bind.annotation.XmlAccessType;
019import javax.xml.bind.annotation.XmlAccessorType;
020import javax.xml.bind.annotation.XmlRootElement;
021
022import service.tut.pori.contentanalysis.CAContentCore.ServiceType;
023import service.tut.pori.contentanalysis.CAContentCore.Visibility;
024import core.tut.pori.users.UserIdentity;
025import core.tut.pori.utils.MediaUrlValidator.MediaType;
026
027/**
028 * Contains metadata information of a single photo.
029 * 
030 * <h2>Optional elements</h2>
031 * <ul>
032 *  <li>{@value service.tut.pori.contentanalysis.Definitions#ELEMENT_BACKEND_STATUS_LIST}</li>
033 *  <li>{@value service.tut.pori.contentanalysis.Definitions#ELEMENT_CONFIDENCE}</li>
034 *  <li>{@value service.tut.pori.contentanalysis.Definitions#ELEMENT_CREDITS}</li>
035 *  <li>{@value service.tut.pori.contentanalysis.Definitions#ELEMENT_DESCRIPTION}</li>
036 *  <li>{@value service.tut.pori.contentanalysis.Definitions#ELEMENT_NAME}</li>
037 *  <li>{@value service.tut.pori.contentanalysis.Definitions#ELEMENT_MEDIA_OBJECTLIST}</li>
038 *  <li>{@value service.tut.pori.contentanalysis.Definitions#ELEMENT_VISIBILITY}</li>
039 * </ul>
040 * 
041 * <h2>Back-end Photo List elements</h2>
042 * 
043 * Certain elements are not applicable when Photo is used with back-end responses. The following elements can be omitted in back-end responses:
044 * <ul>
045 *  <li>{@value service.tut.pori.contentanalysis.Definitions#ELEMENT_SERVICE_ID}</li>
046 *  <li>{@value service.tut.pori.contentanalysis.Definitions#ELEMENT_URL}</li>
047 *  <li>{@value core.tut.pori.users.Definitions#ELEMENT_USER_ID}</li>
048 * </ul>
049 * 
050 * The elements will be ignored, and thus, will not cause errors.
051 * 
052 * <h3>XML Example</h3>
053 * 
054 * {@doc.restlet service="[service.tut.pori.contentanalysis.reference.Definitions#SERVICE_CA_REFERENCE_EXAMPLE]" method="[service.tut.pori.contentanalysis.Definitions#ELEMENT_PHOTO]" type="GET" query="" body_uri=""}
055 * 
056 * @see service.tut.pori.contentanalysis.BackendStatusList
057 * @see service.tut.pori.contentanalysis.MediaObjectList
058 */
059@XmlRootElement(name=Definitions.ELEMENT_PHOTO)
060@XmlAccessorType(XmlAccessType.NONE)
061public class Photo extends Media {
062  /** Default media type for photo */
063  public static final MediaType MEDIA_TYPE = MediaType.PHOTO;
064  
065  /**
066   * for serialization, must be public for solr.
067   */
068  public Photo(){
069    super.setMediaType(MEDIA_TYPE);
070  }
071  
072  /**
073   * 
074   * @param guid
075   */
076  public Photo(String guid){
077    super(guid);
078    super.setMediaType(MEDIA_TYPE);
079  }
080  
081  /**
082   * 
083   * @param guid
084   * @param ownerUserId
085   * @param serviceType
086   * @param visibility
087   */
088  public Photo(String guid, UserIdentity ownerUserId, ServiceType serviceType, Visibility visibility){
089    super(guid, ownerUserId, serviceType, visibility);
090    super.setMediaType(MEDIA_TYPE);
091  }
092  
093  /**
094   * If URL is not set, this will try to generate default redirect URL with serviceId, and GUID,
095   * finally, returns null if the required information is not available.
096   * 
097   * Default data groups: {@value core.tut.pori.http.parameters.DataGroups#DATA_GROUP_BASIC}, {@value core.tut.pori.http.parameters.DataGroups#DATA_GROUP_DEFAULTS}
098   * 
099   * @return URL
100   * @see #setUrl(String)
101   */
102  @Override
103  public String getUrl() {
104    String url = super.getUrl();
105    if(url != null){
106      return url;
107    }else{
108      return CAContentCore.generateRedirectUrl(getGUID(), getServiceType());
109    }
110  }
111
112  /**
113   * @param mediaType if null, the default media type will be used
114   * @throws IllegalArgumentException on bad media type, i.e. not the default media or null
115   * @see #MEDIA_TYPE
116   */
117  @Override
118  public void setMediaType(MediaType mediaType) throws IllegalArgumentException {
119    if(mediaType != null && !MEDIA_TYPE.equals(mediaType)){ // the pre-defined media type cannot be changed, so only check if the value being set is valid
120      throw new IllegalArgumentException("Invalid media type for photo : "+mediaType.name());
121    }
122  }
123}