View Javadoc
1   package org.hl7.fhir.instance.model.api;
2   
3   
4   
5   /*
6    * #%L
7    * HAPI FHIR - Core Library
8    * %%
9    * Copyright (C) 2014 - 2018 University Health Network
10   * %%
11   * Licensed under the Apache License, Version 2.0 (the "License");
12   * you may not use this file except in compliance with the License.
13   * You may obtain a copy of the License at
14   * 
15   *      http://www.apache.org/licenses/LICENSE-2.0
16   * 
17   * Unless required by applicable law or agreed to in writing, software
18   * distributed under the License is distributed on an "AS IS" BASIS,
19   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20   * See the License for the specific language governing permissions and
21   * limitations under the License.
22   * #L%
23   */
24  
25  /**
26   * Base interface for ID datatype. 
27   * 
28   * <p>
29   * <b>Concrete Implementations:</b> This interface is often returned and/or accepted by methods in HAPI's API
30   * where either {@link ca.uhn.fhir.model.primitive.IdDt} (the HAPI structure ID type) or 
31   * <code>org.hl7.fhir.instance.model.IdType</code> (the RI structure ID type) will be used, depending on 
32   * which version of the strctures your application is using.   
33   * </p>
34   */
35  public interface IIdType extends IPrimitiveType<String> {
36  
37  	void applyTo(IBaseResource theResource);
38  
39  	/**
40  	 * Returns the server base URL if this ID contains one. For example, the base URL is
41  	 * the 'http://example.com/fhir' in the following ID: <code>http://example.com/fhir/Patient/123/_history/55</code>
42  	 */
43  	String getBaseUrl();
44  
45  	/**
46  	 * Returns only the logical ID part of this ID. For example, given the ID
47  	 * "http://example,.com/fhir/Patient/123/_history/456", this method would
48  	 * return "123".
49  	 */
50  	String getIdPart();
51  
52  	/**
53  	 * Returns the ID part of this ID (e.g. in the ID http://example.com/Patient/123/_history/456 this would be the
54  	 * part "123") parsed as a {@link Long}.
55  	 * 
56  	 * @throws NumberFormatException If the value can't be parsed as a long
57  	 */
58  	Long getIdPartAsLong();
59  
60  	String getResourceType();
61  
62  	/**
63  	 * 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.
64  	 * 
65  	 * @see #getIdPart()
66  	 */
67  	@Override
68  	String getValue();
69  
70  	String getVersionIdPart();
71  
72  	/**
73  	 * Returns the version ID part of this ID (e.g. in the ID http://example.com/Patient/123/_history/456 this would be the
74  	 * part "456") parsed as a {@link Long}.
75  	 * 
76  	 * @throws NumberFormatException If the value can't be parsed as a long
77  	 */
78  	Long getVersionIdPartAsLong();
79  
80  	boolean hasBaseUrl();
81  
82  	/**
83  	 * Returns <code>true</code> if this ID contains an actual ID part. For example, the ID part is
84  	 * the '123' in the following ID: <code>http://example.com/fhir/Patient/123/_history/55</code>;
85  	 */
86  	boolean hasIdPart();
87  
88  	boolean hasResourceType();
89  
90  	boolean hasVersionIdPart();
91  
92  	/**
93  	 * Returns <code>true</code> if this ID contains an absolute URL (in other words, a URL starting with "http://" or "https://"
94  	 */
95  	boolean isAbsolute();
96  
97  	@Override
98  	boolean isEmpty();
99  
100 	/**
101 	 * Returns <code>true</code> if the {@link #getIdPart() ID part of this object} is valid according to the FHIR rules for valid IDs. 
102 	 * <p>
103 	 * The FHIR specification states:
104 	 * <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>
105 	 * </p>
106 	 */
107 	boolean isIdPartValid();
108 
109 	/**
110 	 * Returns <code>true</code> if the {@link #getIdPart() ID part of this object} contains
111 	 * only numbers 
112 	 */
113 	boolean isIdPartValidLong();
114 
115 	/**
116 	 * Returns <code>true</code> if the ID is a local reference (in other words, it begins with the '#' character)
117 	 */
118 	boolean isLocal();
119 
120 	/**
121 	 * Returns <code>true</code> if the {@link #getVersionIdPart() version ID part of this object} contains
122 	 * only numbers 
123 	 */
124 	boolean isVersionIdPartValidLong();
125 
126 	@Override
127 	IIdType setValue(String theString);
128 
129 	IIdType toUnqualified();
130 
131 	IIdType toUnqualifiedVersionless();
132 
133 	IIdType toVersionless();
134 
135 	/**
136 	 * Returns a copy of this object, but with a different {@link #getResourceType() resource type} 
137 	 * (or if this object does not have a resource type currently, returns a copy of this object with
138 	 * the given resource type).
139 	 * <p>
140 	 * Note that if this object represents a local reference (e.g. <code>#foo</code>) or
141 	 * a URN (e.g. <code>urn:oid:1.2.3.4</code>) this method will simply return a copy
142 	 * of this object with no modifications.
143 	 * </p>
144 	 */
145 	IIdType withResourceType(String theResName);
146 	
147 	/**
148 	 * Returns a copy of this object, but with a different {@link #getResourceType() resource type} 
149 	 * and {@link #getBaseUrl() base URL}
150 	 * (or if this object does not have a resource type currently, returns a copy of this object with
151 	 * the given server base and resource type).
152 	 * <p>
153 	 * Note that if this object represents a local reference (e.g. <code>#foo</code>) or
154 	 * a URN (e.g. <code>urn:oid:1.2.3.4</code>) this method will simply return a copy
155 	 * of this object with no modifications.
156 	 * </p>
157 	 */
158 	IIdType withServerBase(String theServerBase, String theResourceName);
159 
160 	/**
161 	 * Returns a copy of this object, but with a different {@link #getVersionIdPart() version ID} 
162 	 * (or if this object does not have a resource type currently, returns a copy of this object with
163 	 * the given version).
164 	 * <p>
165 	 * Note that if this object represents a local reference (e.g. <code>#foo</code>) or
166 	 * a URN (e.g. <code>urn:oid:1.2.3.4</code>) this method will simply return a copy
167 	 * of this object with no modifications.
168 	 * </p>
169 	 */
170 	IIdType withVersion(String theVersion);
171 
172 	/**
173 	 * Sets the value of this ID by combining all of the individual parts.
174 	 * <p>
175 	 * <b>Required parameters:</b> The following rules apply to the parameters of this method (in this case, populated means
176 	 * a non-empty string and not populated means <code>null</code> or an empty string)
177 	 * </p>
178 	 * <ul>
179 	 * <li>All values may be not populated</li>
180 	 * <li>If <b>theVersionIdPart</b> is populated, <b>theResourceType</b> and <b>theIdPart</b> must be populated</li>
181 	 * <li>If <b>theBaseUrl</b> is populated and <b>theIdPart</b> is populated, <b>theResourceType</b> must be populated</li>
182 	 * </ul>
183 	 * 
184 	 * @return Returns a reference to <code>this</code> for easy method chaining
185 	 */
186 	IIdType setParts(String theBaseUrl, String theResourceType, String theIdPart, String theVersionIdPart);
187 
188 }