ca.uhn.fhir.model.api.ResourceMetadataKeyEnum Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of hapi-fhir-base Show documentation
Builds the hapi fhir base. Requires Common lang, commons-text, and guava be built first.
There is a newer version: 7.0.2-r12
/*
 * #%L
 * HAPI FHIR - Core Library
 * %%
 * Copyright (C) 2014 - 2024 Smile CDR, Inc.
 * %%
 * 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.
 * #L%
 */
package ca.uhn.fhir.model.api;

import ca.uhn.fhir.i18n.Msg;
import ca.uhn.fhir.model.base.composite.BaseCodingDt;
import ca.uhn.fhir.model.primitive.IdDt;
import ca.uhn.fhir.model.primitive.InstantDt;
import ca.uhn.fhir.model.valueset.BundleEntrySearchModeEnum;
import ca.uhn.fhir.model.valueset.BundleEntryTransactionMethodEnum;
import ca.uhn.fhir.rest.server.exceptions.InternalErrorException;
import org.hl7.fhir.instance.model.api.IAnyResource;
import org.hl7.fhir.instance.model.api.IBaseResource;
import org.hl7.fhir.instance.model.api.IPrimitiveType;

import java.io.Serializable;
import java.util.Date;
import java.util.List;

/**
 * Keys in this map refer to resource metadata keys, which are keys used to access information about specific resource instances that live outside of the resource body. Typically, these are
 * data elements which are sent/receieved in HTTP Headers along with read/create resource requests, or properties which can be found in bundle entries.
 * 
 * To access or set resource metadata values, every resource has a metadata map, and this class provides convenient getters/setters for interacting with that map. For example, to get a resource's
 * {@link #UPDATED} value, which is the "last updated" time for that resource, use the following code:
 * 
 * 
 * InstantDt updated = ResourceMetadataKeyEnum.UPDATED.get(resource);
 * 

 * 

 * To set this value, use the following:
 * 
 * 
 * InstantDt update = new InstantDt("2011-01-02T11:22:33.0000Z"); // populate with the actual time

 * ResourceMetadataKeyEnum.UPDATED.put(resource, update);
 * 
 * 
 * Note that this class is not a Java Enum, and can therefore be extended (this is why it is not actually an Enum). Users of HAPI-FHIR are able to create their own classes extending this class to
 * define their own keys for storage in resource metadata if needed.
 * 
 */
public abstract class ResourceMetadataKeyEnum implements Serializable {

	/**
	 * If present and populated with a date/time (as an instance of {@link InstantDt}), this value is an indication that the resource is in the deleted state. This key is only used in a limited number
	 * of scenarios, such as POSTing transaction bundles to a server, or returning resource history.
	 * 
	 * Values for this key are of type {@link InstantDt}
	 * 
	 */
	public static final ResourceMetadataKeyEnum> DELETED_AT =
			new ResourceMetadataKeyEnum<>("DELETED_AT", IPrimitiveType.class) {};
	/**
	 * If present and populated with a {@link BundleEntrySearchModeEnum}, contains the "bundle entry search mode", which is the value of the status field in the Bundle entry containing this resource.
	 * The value for this key corresponds to field Bundle.entry.search.mode. This value can be set to provide a status value of "include" for included resources being returned by a
	 * server, or to "match" to indicate that the resource was returned because it matched the given search criteria.
	 * 
	 * Note that status is only used in FHIR DSTU2 and later.
	 * 
	 * 
	 * Values for this key are of type {@link BundleEntrySearchModeEnum}
	 * 
	 */
	public static final ResourceMetadataKeyEnum ENTRY_SEARCH_MODE =
			new ResourceMetadataKeyEnum<>("ENTRY_SEARCH_MODE", BundleEntrySearchModeEnum.class) {};
	/**
	 * If present and populated with a {@link BundleEntryTransactionMethodEnum}, contains the "bundle entry transaction operation", which is the value of the status field in the Bundle entry
	 * containing this resource. The value for this key corresponds to field Bundle.entry.transaction.operation. This value can be set in resources being transmitted to a server to
	 * provide a status value of "create" or "update" to indicate behaviour the server should observe. It may also be set to similar values (or to "noop") in resources being returned by a server as a
	 * result of a transaction to indicate to the client what operation was actually performed.
	 * 
	 * Note that status is only used in FHIR DSTU2 and later.
	 * 
	 * 
	 * Values for this key are of type {@link BundleEntryTransactionMethodEnum}
	 * 
	 */
	public static final ResourceMetadataKeyEnum ENTRY_TRANSACTION_METHOD =
			new ResourceMetadataKeyEnum<>("ENTRY_TRANSACTION_OPERATION", BundleEntryTransactionMethodEnum.class) {};
	/**
	 * The value for this key represents a {@link List} of profile IDs that this resource claims to conform to.
	 * 
	 * 

	 * Values for this key are of type List<IdDt>. Note that the returned list is unmodifiable, so you need to create a new list and call put to change its value.
	 * 
	 */
	public static final ResourceMetadataKeyEnum> PROFILES =
			new ResourceMetadataKeyEnum<>("PROFILES", List.class) {};
	/**
	 * The value for this key is the bundle entry Published time. This is defined by FHIR as "Time resource copied into the feed", which is generally best left to the current time.
	 * 
	 * Values for this key are of type {@link InstantDt}
	 * 
	 * 
	 * Server Note: In servers, it is generally advisable to leave this value null, in which case the server will substitute the current time automatically.
	 * 
	 *
	 * @see InstantDt
	 */
	public static final ResourceMetadataKeyEnum PUBLISHED =
			new ResourceMetadataKeyEnum<>("PUBLISHED", InstantDt.class) {};

	public static final ResourceMetadataKeyEnum> SECURITY_LABELS =
			new ResourceMetadataKeyEnum<>("SECURITY_LABELS", List.class) {};
	/**
	 * The value for this key is the list of tags associated with this resource
	 * 
	 * Values for this key are of type {@link TagList}
	 * 
	 *
	 * @see TagList
	 */
	public static final ResourceMetadataKeyEnum TAG_LIST =
			new ResourceMetadataKeyEnum<>("TAG_LIST", TagList.class) {};
	/**
	 * The value for this key is the bundle entry Updated time. This is defined by FHIR as "Last Updated for resource". This value is also used for populating the "Last-Modified" header in the
	 * case of methods that return a single resource (read, vread, etc.)
	 * 
	 * Values for this key are of type {@link InstantDt}
	 * 
	 *
	 * @see InstantDt
	 */
	public static final ResourceMetadataKeyEnum UPDATED =
			new ResourceMetadataKeyEnum<>("UPDATED", InstantDt.class) {};
	/**
	 * The value for this key is the version ID of the resource object.
	 * 
	 * Values for this key are of type {@link String}
	 * 
	 *
	 * @deprecated The {@link IResource#getId()} resource ID will now be populated with the version ID via the {@link IdDt#getVersionIdPart()} method
	 */
	@Deprecated
	public static final ResourceMetadataKeyEnum VERSION =
			new ResourceMetadataKeyEnum<>("VERSION", String.class) {};
	/**
	 * The value for this key is the version ID of the resource object.
	 * 
	 * Values for this key are of type {@link IdDt}
	 * 
	 *
	 * @deprecated The {@link IResource#getId()} resource ID will now be populated with the version ID via the {@link IdDt#getVersionIdPart()} method
	 */
	@Deprecated
	public static final ResourceMetadataKeyEnum VERSION_ID =
			new ResourceMetadataKeyEnum<>("VERSION_ID", IdDt.class) {};

	private static final long serialVersionUID = 1L;
	private final String myValue;
	private final Class myType;

	public ResourceMetadataKeyEnum(String theValue, Class theType) {
		myValue = theValue;
		myType = theType;
	}

	// TODO: JA - Replace all of the various other get/put methods in subclasses with just using the two that are here
	public T get(IBaseResource theResource) {
		Object retVal;
		if (theResource instanceof IAnyResource) {
			retVal = theResource.getUserData(name());
		} else {
			retVal = ((IResource) theResource).getResourceMetadata().get(this);
		}

		if (retVal != null && !myType.isAssignableFrom(retVal.getClass())) {
			throw new InternalErrorException(Msg.code(1890) + "Found an object of type '"
					+ retVal.getClass().getCanonicalName()
					+ "' in resource metadata for key " + this.name() + " - Expected "
					+ myType.getCanonicalName());
		}

		//noinspection unchecked
		return (T) retVal;
	}

	public void put(IBaseResource theResource, T theValue) {
		if (theValue != null && !myType.isAssignableFrom(theValue.getClass())) {
			throw new InternalErrorException(Msg.code(1891) + "Can not put object of type '"
					+ theValue.getClass().getCanonicalName()
					+ "' in resource metadata for key " + this.name() + " - Expected "
					+ myType.getCanonicalName());
		}

		if (theResource instanceof IAnyResource) {
			theResource.setUserData(name(), theValue);
		} else {
			((IResource) theResource).getResourceMetadata().put(this, theValue);
		}
	}

	@Override
	public boolean equals(Object obj) {
		if (this == obj) return true;
		if (obj == null) return false;
		if (getClass() != obj.getClass()) return false;
		ResourceMetadataKeyEnum other = (ResourceMetadataKeyEnum) obj;
		if (myValue == null) {
			return other.myValue == null;
		} else return myValue.equals(other.myValue);
	}

	@Override
	public int hashCode() {
		final int prime = 31;
		int result = 1;
		result = prime * result + ((myValue == null) ? 0 : myValue.hashCode());
		return result;
	}

	public String name() {
		return myValue;
	}

	public static final class ExtensionResourceMetadataKey extends ResourceMetadataKeyEnum {
		public ExtensionResourceMetadataKey(String theUrl) {
			super(theUrl, ExtensionDt.class);
		}
	}
}