001package ca.uhn.fhir.model.api;
002
003import org.hl7.fhir.instance.model.api.IBaseMetaType;
004
005/*
006 * #%L
007 * HAPI FHIR - Core Library
008 * %%
009 * Copyright (C) 2014 - 2023 Smile CDR, Inc.
010 * %%
011 * Licensed under the Apache License, Version 2.0 (the "License");
012 * you may not use this file except in compliance with the License.
013 * You may obtain a copy of the License at
014 *
015 *      http://www.apache.org/licenses/LICENSE-2.0
016 *
017 * Unless required by applicable law or agreed to in writing, software
018 * distributed under the License is distributed on an "AS IS" BASIS,
019 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
020 * See the License for the specific language governing permissions and
021 * limitations under the License.
022 * #L%
023 */
024
025import ca.uhn.fhir.model.api.annotation.ResourceDef;
026import ca.uhn.fhir.model.base.composite.BaseContainedDt;
027import ca.uhn.fhir.model.base.composite.BaseNarrativeDt;
028import ca.uhn.fhir.model.base.resource.ResourceMetadataMap;
029import ca.uhn.fhir.model.primitive.CodeDt;
030import ca.uhn.fhir.model.primitive.IdDt;
031
032/**
033 * This interface is the parent interface for all FHIR Resource definition classes. Classes implementing this interface should be annotated with the {@link ResourceDef @ResourceDef} annotation.
034 * 
035 * <p>
036 * Note that this class is a part of HAPI's model API, used to define structure classes. Users will often interact with this interface, but should not need to implement it directly.
037 * </p>
038 */
039public interface IResource extends ICompositeElement, org.hl7.fhir.instance.model.api.IBaseResource {
040
041        /**
042         * Returns the contained resource list for this resource.
043         * <p>
044         * Usage note: HAPI will generally populate and use the resources from this list automatically (placing inline resources in the contained list when encoding, and copying contained resources from
045         * this list to their appropriate references when parsing) so it is generally not neccesary to interact with this list directly. Instead, in a server you can place resource instances in reference
046         * fields (such as <code>Patient#setManagingOrganization(ResourceReferenceDt)</code> ) and the resource will be automatically contained. In a client, contained resources will be automatically
047         * populated into their appropriate fields by the HAPI parser.
048         * </p>
049         * TODO: document contained resources and link there
050         */
051        BaseContainedDt getContained();
052
053        /**
054         * Returns the ID of this resource. Note that this identifier is the URL (or a portion of the URL) used to access this resource, and is not the same thing as any business identifiers stored within
055         * the resource. For example, a Patient resource might have any number of medical record numbers but these are not stored here.
056         * <p>
057         * This ID is specified as the "Logical ID" and "Version ID" in the FHIR specification, see <a href="http://www.hl7.org/implement/standards/fhir/resources.html#metadata">here</a>
058         * </p>
059         */
060        IdDt getId();
061
062        /**
063         * Gets the language of the resource itself - <b>NOTE that this language attribute applies to the resource itself, it is not (for example) the language spoken by a practitioner or patient</b>
064         */
065        CodeDt getLanguage();
066
067        /**
068         * Returns a view of the {@link #getResourceMetadata() resource metadata} map.
069         * Note that getters from this map return immutable objects, but the <code>addFoo()</code>
070         * and <code>setFoo()</code> methods may be used to modify metadata. 
071         * 
072         * @since 1.5
073         */
074        @Override
075        IBaseMetaType getMeta();
076
077        /**
078         * Returns the metadata map for this object, creating it if neccesary. Metadata entries are used to get/set feed bundle entries, such as the resource version, or the last updated timestamp.
079         * <p>
080         * Keys in this map are enumerated in the {@link ResourceMetadataKeyEnum}, and each key has a specific value type that it must use.
081         * </p>
082         * 
083         * @see ResourceMetadataKeyEnum for a list of allowable keys and the object types that values of a given key must use.
084         */
085        ResourceMetadataMap getResourceMetadata();
086
087        /**
088         * Returns a String representing the name of this Resource. This return value is not used for anything by HAPI itself, but is provided as a convenience to developers using the API.
089         * 
090         * @return the name of this resource, e.g. "Patient", or "Observation"
091         */
092        String getResourceName();
093
094        /**
095         * Returns the FHIR version represented by this structure
096         */
097        @Override
098        public ca.uhn.fhir.context.FhirVersionEnum getStructureFhirVersionEnum();
099
100        /**
101         * Returns the narrative block for this resource
102         */
103        BaseNarrativeDt<?> getText();
104
105        /**
106         * Sets the ID of this resource. Note that this identifier is the URL (or a portion of the URL) used to access this resource, and is not the same thing as any business identifiers stored within the
107         * resource. For example, a Patient resource might have any number of medical record numbers but these are not stored here.
108         * <p>
109         * This ID is specified as the "Logical ID" and "Version ID" in the FHIR specification, see <a href="http://www.hl7.org/implement/standards/fhir/resources.html#metadata">here</a>
110         * </p>
111         */
112        void setId(IdDt theId);
113
114        /**
115         * Sets the language of the resource itself - <b>NOTE that this language attribute applies to the resource itself, it is not (for example) the language spoken by a practitioner or patient</b>
116         */
117        void setLanguage(CodeDt theLanguage);
118
119        /**
120         * Sets the metadata map for this object. Metadata entries are used to get/set feed bundle entries, such as the resource version, or the last updated timestamp.
121         * 
122         * @throws NullPointerException
123         *            The map must not be null
124         */
125        void setResourceMetadata(ResourceMetadataMap theMap);
126
127}