001package org.hl7.fhir.instance.model.api;
002
003
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
025/**
026 * Base interface for ID datatype. 
027 * 
028 * <p>
029 * <b>Concrete Implementations:</b> This interface is often returned and/or accepted by methods in HAPI's API
030 * where either {@link ca.uhn.fhir.model.primitive.IdDt} (the HAPI structure ID type) or 
031 * <code>org.hl7.fhir.instance.model.IdType</code> (the RI structure ID type) will be used, depending on 
032 * which version of the strctures your application is using.   
033 * </p>
034 */
035public interface IIdType extends IPrimitiveType<String> {
036
037        void applyTo(IBaseResource theResource);
038
039        /**
040         * Returns the server base URL if this ID contains one. For example, the base URL is
041         * the 'http://example.com/fhir' in the following ID: <code>http://example.com/fhir/Patient/123/_history/55</code>
042         */
043        String getBaseUrl();
044
045        /**
046         * Returns only the logical ID part of this ID. For example, given the ID
047         * "http://example,.com/fhir/Patient/123/_history/456", this method would
048         * return "123".
049         */
050        String getIdPart();
051
052        /**
053         * Returns the ID part of this ID (e.g. in the ID http://example.com/Patient/123/_history/456 this would be the
054         * part "123") parsed as a {@link Long}.
055         * 
056         * @throws NumberFormatException If the value can't be parsed as a long
057         */
058        Long getIdPartAsLong();
059
060        String getResourceType();
061
062
063        /**
064         * Returns the value of this ID. Note that this value may be a fully qualified URL, a relative/partial URL, or a simple ID. Use {@link #getIdPart()} to get just the ID portion.
065         * 
066         * @see #getIdPart()
067         */
068        @Override
069        String getValue();
070
071        String getVersionIdPart();
072
073        /**
074         * Returns the version ID part of this ID (e.g. in the ID http://example.com/Patient/123/_history/456 this would be the
075         * part "456") parsed as a {@link Long}.
076         * 
077         * @throws NumberFormatException If the value can't be parsed as a long
078         */
079        Long getVersionIdPartAsLong();
080
081        boolean hasBaseUrl();
082
083        /**
084         * Returns <code>true</code> if this ID contains an actual ID part. For example, the ID part is
085         * the '123' in the following ID: <code>http://example.com/fhir/Patient/123/_history/55</code>
086         */
087        boolean hasIdPart();
088
089        boolean hasResourceType();
090
091        boolean hasVersionIdPart();
092
093        /**
094         * Returns <code>true</code> if this ID contains an absolute URL (in other words, a URL starting with "http://" or "https://"
095         */
096        boolean isAbsolute();
097
098        @Override
099        boolean isEmpty();
100
101        /**
102         * Returns <code>true</code> if the {@link #getIdPart() ID part of this object} is valid according to the FHIR rules for valid IDs. 
103         * <p>
104         * The FHIR specification states:
105         * <code>Any combination of upper or lower case ASCII letters ('A'..'Z', and 'a'..'z', numerals ('0'..'9'), '-' and '.', with a length limit of 64 characters. (This might be an integer, an un-prefixed OID, UUID or any other identifier pattern that meets these constraints.) regex: [A-Za-z0-9\-\.]{1,64}</code>
106         * </p>
107         */
108        boolean isIdPartValid();
109
110        /**
111         * Returns <code>true</code> if the {@link #getIdPart() ID part of this object} contains
112         * only numbers 
113         */
114        boolean isIdPartValidLong();
115
116        /**
117         * Returns <code>true</code> if the ID is a local reference (in other words, it begins with the '#' character)
118         */
119        boolean isLocal();
120
121        /**
122         * Returns <code>true</code> if the {@link #getVersionIdPart() version ID part of this object} contains
123         * only numbers 
124         */
125        boolean isVersionIdPartValidLong();
126
127        @Override
128        IIdType setValue(String theString);
129
130        IIdType toUnqualified();
131
132        IIdType toUnqualifiedVersionless();
133
134        IIdType toVersionless();
135
136        /**
137         * Returns a copy of this object, but with a different {@link #getResourceType() resource type} 
138         * (or if this object does not have a resource type currently, returns a copy of this object with
139         * the given resource type).
140         * <p>
141         * Note that if this object represents a local reference (e.g. <code>#foo</code>) or
142         * a URN (e.g. <code>urn:oid:1.2.3.4</code>) this method will simply return a copy
143         * of this object with no modifications.
144         * </p>
145         */
146        IIdType withResourceType(String theResName);
147        
148        /**
149         * Returns a copy of this object, but with a different {@link #getResourceType() resource type} 
150         * and {@link #getBaseUrl() base URL}
151         * (or if this object does not have a resource type currently, returns a copy of this object with
152         * the given server base and resource type).
153         * <p>
154         * Note that if this object represents a local reference (e.g. <code>#foo</code>) or
155         * a URN (e.g. <code>urn:oid:1.2.3.4</code>) this method will simply return a copy
156         * of this object with no modifications.
157         * </p>
158         */
159        IIdType withServerBase(String theServerBase, String theResourceName);
160
161        /**
162         * Returns a copy of this object, but with a different {@link #getVersionIdPart() version ID} 
163         * (or if this object does not have a resource type currently, returns a copy of this object with
164         * the given version).
165         * <p>
166         * Note that if this object represents a local reference (e.g. <code>#foo</code>) or
167         * a URN (e.g. <code>urn:oid:1.2.3.4</code>) this method will simply return a copy
168         * of this object with no modifications.
169         * </p>
170         */
171        IIdType withVersion(String theVersion);
172
173        /**
174         * Sets the value of this ID by combining all of the individual parts.
175         * <p>
176         * <b>Required parameters:</b> The following rules apply to the parameters of this method (in this case, populated means
177         * a non-empty string and not populated means <code>null</code> or an empty string)
178         * </p>
179         * <ul>
180         * <li>All values may be not populated</li>
181         * <li>If <b>theVersionIdPart</b> is populated, <b>theResourceType</b> and <b>theIdPart</b> must be populated</li>
182         * <li>If <b>theBaseUrl</b> is populated and <b>theIdPart</b> is populated, <b>theResourceType</b> must be populated</li>
183         * </ul>
184         * 
185         * @return Returns a reference to <code>this</code> for easy method chaining
186         */
187        IIdType setParts(String theBaseUrl, String theResourceType, String theIdPart, String theVersionIdPart);
188
189}