
001/* 002 * #%L 003 * HAPI FHIR - Core Library 004 * %% 005 * Copyright (C) 2014 - 2025 Smile CDR, Inc. 006 * %% 007 * Licensed under the Apache License, Version 2.0 (the "License"); 008 * you may not use this file except in compliance with the License. 009 * You may obtain a copy of the License at 010 * 011 * http://www.apache.org/licenses/LICENSE-2.0 012 * 013 * Unless required by applicable law or agreed to in writing, software 014 * distributed under the License is distributed on an "AS IS" BASIS, 015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 016 * See the License for the specific language governing permissions and 017 * limitations under the License. 018 * #L% 019 */ 020package org.hl7.fhir.instance.model.api; 021 022/** 023 * Base interface for ID datatype. 024 * 025 * <p> 026 * <b>Concrete Implementations:</b> This interface is often returned and/or accepted by methods in HAPI's API 027 * where either {@link ca.uhn.fhir.model.primitive.IdDt} (the HAPI structure ID type) or 028 * <code>org.hl7.fhir.instance.model.IdType</code> (the RI structure ID type) will be used, depending on 029 * which version of the strctures your application is using. 030 * </p> 031 */ 032public interface IIdType extends IPrimitiveType<String> { 033 034 void applyTo(IBaseResource theResource); 035 036 /** 037 * Returns the server base URL if this ID contains one. For example, the base URL is 038 * the 'http://example.com/fhir' in the following ID: <code>http://example.com/fhir/Patient/123/_history/55</code> 039 */ 040 String getBaseUrl(); 041 042 /** 043 * Returns only the logical ID part of this ID. For example, given the ID 044 * "http://example,.com/fhir/Patient/123/_history/456", this method would 045 * return "123". 046 */ 047 String getIdPart(); 048 049 /** 050 * Returns the ID part of this ID (e.g. in the ID http://example.com/Patient/123/_history/456 this would be the 051 * part "123") parsed as a {@link Long}. 052 * 053 * @throws NumberFormatException If the value can't be parsed as a long 054 */ 055 Long getIdPartAsLong(); 056 057 String getResourceType(); 058 059 /** 060 * 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. 061 * 062 * @see #getIdPart() 063 */ 064 @Override 065 String getValue(); 066 067 String getVersionIdPart(); 068 069 /** 070 * Returns the version ID part of this ID (e.g. in the ID http://example.com/Patient/123/_history/456 this would be the 071 * part "456") parsed as a {@link Long}. 072 * 073 * @throws NumberFormatException If the value can't be parsed as a long 074 */ 075 Long getVersionIdPartAsLong(); 076 077 boolean hasBaseUrl(); 078 079 /** 080 * Returns <code>true</code> if this ID contains an actual ID part. For example, the ID part is 081 * the '123' in the following ID: <code>http://example.com/fhir/Patient/123/_history/55</code> 082 */ 083 boolean hasIdPart(); 084 085 boolean hasResourceType(); 086 087 boolean hasVersionIdPart(); 088 089 /** 090 * Returns <code>true</code> if this ID contains an absolute URL (in other words, a URL starting with "http://" or "https://" 091 */ 092 boolean isAbsolute(); 093 094 @Override 095 boolean isEmpty(); 096 097 /** 098 * Returns <code>true</code> if the {@link #getIdPart() ID part of this object} is valid according to the FHIR rules for valid IDs. 099 * <p> 100 * The FHIR specification states: 101 * <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> 102 * </p> 103 */ 104 boolean isIdPartValid(); 105 106 /** 107 * Returns <code>true</code> if the {@link #getIdPart() ID part of this object} contains 108 * only numbers 109 */ 110 boolean isIdPartValidLong(); 111 112 /** 113 * Returns <code>true</code> if the ID is a local reference (in other words, it begins with the '#' character) 114 */ 115 boolean isLocal(); 116 117 /** 118 * Returns <code>true</code> if the {@link #getVersionIdPart() version ID part of this object} contains 119 * only numbers 120 */ 121 boolean isVersionIdPartValidLong(); 122 123 /** 124 * @return true if the id begins with "urn:uuid:" 125 */ 126 default boolean isUuid() { 127 return getValue() != null && getValue().startsWith("urn:uuid:"); 128 } 129 130 @Override 131 IIdType setValue(String theString); 132 133 IIdType toUnqualified(); 134 135 IIdType toUnqualifiedVersionless(); 136 137 IIdType toVersionless(); 138 139 /** 140 * Returns a copy of this object, but with a different {@link #getResourceType() resource type} 141 * (or if this object does not have a resource type currently, returns a copy of this object with 142 * the given resource type). 143 * <p> 144 * Note that if this object represents a local reference (e.g. <code>#foo</code>) or 145 * a URN (e.g. <code>urn:oid:1.2.3.4</code>) this method will simply return a copy 146 * of this object with no modifications. 147 * </p> 148 */ 149 IIdType withResourceType(String theResName); 150 151 /** 152 * Returns a copy of this object, but with a different {@link #getResourceType() resource type} 153 * and {@link #getBaseUrl() base URL} 154 * (or if this object does not have a resource type currently, returns a copy of this object with 155 * the given server base and resource type). 156 * <p> 157 * Note that if this object represents a local reference (e.g. <code>#foo</code>) or 158 * a URN (e.g. <code>urn:oid:1.2.3.4</code>) this method will simply return a copy 159 * of this object with no modifications. 160 * </p> 161 */ 162 IIdType withServerBase(String theServerBase, String theResourceName); 163 164 /** 165 * Returns a copy of this object, but with a different {@link #getVersionIdPart() version ID} 166 * (or if this object does not have a resource type currently, returns a copy of this object with 167 * the given version). 168 * <p> 169 * Note that if this object represents a local reference (e.g. <code>#foo</code>) or 170 * a URN (e.g. <code>urn:oid:1.2.3.4</code>) this method will simply return a copy 171 * of this object with no modifications. 172 * </p> 173 */ 174 IIdType withVersion(String theVersion); 175 176 /** 177 * Sets the value of this ID by combining all of the individual parts. 178 * <p> 179 * <b>Required parameters:</b> The following rules apply to the parameters of this method (in this case, populated means 180 * a non-empty string and not populated means <code>null</code> or an empty string) 181 * </p> 182 * <ul> 183 * <li>All values may be not populated</li> 184 * <li>If <b>theVersionIdPart</b> is populated, <b>theResourceType</b> and <b>theIdPart</b> must be populated</li> 185 * <li>If <b>theBaseUrl</b> is populated and <b>theIdPart</b> is populated, <b>theResourceType</b> must be populated</li> 186 * </ul> 187 * 188 * @return Returns a reference to <code>this</code> for easy method chaining 189 */ 190 IIdType setParts(String theBaseUrl, String theResourceType, String theIdPart, String theVersionIdPart); 191}