
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}