001/* 002 * #%L 003 * HAPI FHIR - Core Library 004 * %% 005 * Copyright (C) 2014 - 2024 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 @Override 124 IIdType setValue(String theString); 125 126 IIdType toUnqualified(); 127 128 IIdType toUnqualifiedVersionless(); 129 130 IIdType toVersionless(); 131 132 /** 133 * Returns a copy of this object, but with a different {@link #getResourceType() resource type} 134 * (or if this object does not have a resource type currently, returns a copy of this object with 135 * the given resource type). 136 * <p> 137 * Note that if this object represents a local reference (e.g. <code>#foo</code>) or 138 * a URN (e.g. <code>urn:oid:1.2.3.4</code>) this method will simply return a copy 139 * of this object with no modifications. 140 * </p> 141 */ 142 IIdType withResourceType(String theResName); 143 144 /** 145 * Returns a copy of this object, but with a different {@link #getResourceType() resource type} 146 * and {@link #getBaseUrl() base URL} 147 * (or if this object does not have a resource type currently, returns a copy of this object with 148 * the given server base and resource type). 149 * <p> 150 * Note that if this object represents a local reference (e.g. <code>#foo</code>) or 151 * a URN (e.g. <code>urn:oid:1.2.3.4</code>) this method will simply return a copy 152 * of this object with no modifications. 153 * </p> 154 */ 155 IIdType withServerBase(String theServerBase, String theResourceName); 156 157 /** 158 * Returns a copy of this object, but with a different {@link #getVersionIdPart() version ID} 159 * (or if this object does not have a resource type currently, returns a copy of this object with 160 * the given version). 161 * <p> 162 * Note that if this object represents a local reference (e.g. <code>#foo</code>) or 163 * a URN (e.g. <code>urn:oid:1.2.3.4</code>) this method will simply return a copy 164 * of this object with no modifications. 165 * </p> 166 */ 167 IIdType withVersion(String theVersion); 168 169 /** 170 * Sets the value of this ID by combining all of the individual parts. 171 * <p> 172 * <b>Required parameters:</b> The following rules apply to the parameters of this method (in this case, populated means 173 * a non-empty string and not populated means <code>null</code> or an empty string) 174 * </p> 175 * <ul> 176 * <li>All values may be not populated</li> 177 * <li>If <b>theVersionIdPart</b> is populated, <b>theResourceType</b> and <b>theIdPart</b> must be populated</li> 178 * <li>If <b>theBaseUrl</b> is populated and <b>theIdPart</b> is populated, <b>theResourceType</b> must be populated</li> 179 * </ul> 180 * 181 * @return Returns a reference to <code>this</code> for easy method chaining 182 */ 183 IIdType setParts(String theBaseUrl, String theResourceType, String theIdPart, String theVersionIdPart); 184}