001package org.hl7.fhir.r4.hapi.rest.server;
002
003import ca.uhn.fhir.context.FhirVersionEnum;
004import ca.uhn.fhir.context.RuntimeResourceDefinition;
005import ca.uhn.fhir.context.RuntimeSearchParam;
006import ca.uhn.fhir.parser.DataFormatException;
007import ca.uhn.fhir.rest.annotation.IdParam;
008import ca.uhn.fhir.rest.annotation.Metadata;
009import ca.uhn.fhir.rest.annotation.Read;
010import ca.uhn.fhir.rest.api.Constants;
011import ca.uhn.fhir.rest.api.server.RequestDetails;
012import ca.uhn.fhir.rest.server.Bindings;
013import ca.uhn.fhir.rest.server.IServerConformanceProvider;
014import ca.uhn.fhir.rest.server.RestfulServer;
015import ca.uhn.fhir.rest.server.RestfulServerConfiguration;
016import ca.uhn.fhir.rest.server.exceptions.ResourceNotFoundException;
017import ca.uhn.fhir.rest.server.method.*;
018import ca.uhn.fhir.rest.server.method.SearchParameter;
019import ca.uhn.fhir.rest.server.method.OperationMethodBinding.ReturnType;
020import ca.uhn.fhir.rest.server.util.BaseServerCapabilityStatementProvider;
021import org.apache.commons.lang3.StringUtils;
022import org.hl7.fhir.exceptions.FHIRException;
023import org.hl7.fhir.instance.model.api.IBaseResource;
024import org.hl7.fhir.instance.model.api.IPrimitiveType;
025import org.hl7.fhir.r4.model.*;
026import org.hl7.fhir.r4.model.CapabilityStatement.*;
027import org.hl7.fhir.r4.model.Enumerations.PublicationStatus;
028import org.hl7.fhir.r4.model.OperationDefinition.OperationDefinitionParameterComponent;
029import org.hl7.fhir.r4.model.OperationDefinition.OperationKind;
030import org.hl7.fhir.r4.model.OperationDefinition.OperationParameterUse;
031
032import javax.servlet.ServletContext;
033import javax.servlet.http.HttpServletRequest;
034import java.util.*;
035import java.util.Map.Entry;
036
037import static org.apache.commons.lang3.StringUtils.isBlank;
038import static org.apache.commons.lang3.StringUtils.isNotBlank;
039
040import ca.uhn.fhir.context.FhirContext;
041
042/*
043 * #%L
044 * HAPI FHIR Structures - DSTU2 (FHIR v1.0.0)
045 * %%
046 * Copyright (C) 2014 - 2015 University Health Network
047 * %%
048 * Licensed under the Apache License, Version 2.0 (the "License");
049 * you may not use this file except in compliance with the License.
050 * You may obtain a copy of the License at
051 *
052 *      http://www.apache.org/licenses/LICENSE-2.0
053 *
054 * Unless required by applicable law or agreed to in writing, software
055 * distributed under the License is distributed on an "AS IS" BASIS,
056 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
057 * See the License for the specific language governing permissions and
058 * limitations under the License.
059 * #L%
060 */
061
062/**
063 * Server FHIR Provider which serves the conformance statement for a RESTful server implementation
064 *
065 * <p>
066 * Note: This class is safe to extend, but it is important to note that the same instance of {@link CapabilityStatement} is always returned unless {@link #setCache(boolean)} is called with a value of
067 * <code>false</code>. This means that if you are adding anything to the returned conformance instance on each call you should call <code>setCache(false)</code> in your provider constructor.
068 * </p>
069 */
070public class ServerCapabilityStatementProvider extends BaseServerCapabilityStatementProvider implements IServerConformanceProvider<CapabilityStatement> {
071
072  private static final org.slf4j.Logger ourLog = org.slf4j.LoggerFactory.getLogger(ServerCapabilityStatementProvider.class);
073  private String myPublisher = "Not provided";
074
075  /**
076   * No-arg constructor and setter so that the ServerConformanceProvider can be Spring-wired with the RestfulService avoiding the potential reference cycle that would happen.
077   */
078  public ServerCapabilityStatementProvider() {
079    super();
080  }
081
082  /**
083   * Constructor
084   *
085   * @deprecated Use no-args constructor instead. Deprecated in 4.0.0
086   */
087  @Deprecated
088  public ServerCapabilityStatementProvider(RestfulServer theRestfulServer) {
089    this();
090  }
091
092  /**
093   * Constructor - This is intended only for JAX-RS server
094   */
095  public ServerCapabilityStatementProvider(RestfulServerConfiguration theServerConfiguration) {
096    super(theServerConfiguration);
097  }
098
099  private void checkBindingForSystemOps(CapabilityStatementRestComponent rest, Set<SystemRestfulInteraction> systemOps, BaseMethodBinding<?> nextMethodBinding) {
100    if (nextMethodBinding.getRestOperationType() != null) {
101      String sysOpCode = nextMethodBinding.getRestOperationType().getCode();
102      if (sysOpCode != null) {
103        SystemRestfulInteraction sysOp;
104        try {
105          sysOp = SystemRestfulInteraction.fromCode(sysOpCode);
106        } catch (FHIRException e) {
107          return;
108        }
109        if (sysOp == null) {
110          return;
111        }
112        if (systemOps.contains(sysOp) == false) {
113          systemOps.add(sysOp);
114          rest.addInteraction().setCode(sysOp);
115        }
116      }
117    }
118  }
119
120  private DateTimeType conformanceDate(RequestDetails theRequestDetails) {
121    IPrimitiveType<Date> buildDate = getServerConfiguration(theRequestDetails).getConformanceDate();
122    if (buildDate != null && buildDate.getValue() != null) {
123      try {
124        return new DateTimeType(buildDate.getValueAsString());
125      } catch (DataFormatException e) {
126        // fall through
127      }
128    }
129    return DateTimeType.now();
130  }
131
132
133  /**
134   * Gets the value of the "publisher" that will be placed in the generated conformance statement. As this is a mandatory element, the value should not be null (although this is not enforced). The
135   * value defaults to "Not provided" but may be set to null, which will cause this element to be omitted.
136   */
137  public String getPublisher() {
138    return myPublisher;
139  }
140
141  /**
142   * Sets the value of the "publisher" that will be placed in the generated conformance statement. As this is a mandatory element, the value should not be null (although this is not enforced). The
143   * value defaults to "Not provided" but may be set to null, which will cause this element to be omitted.
144   */
145  public void setPublisher(String thePublisher) {
146    myPublisher = thePublisher;
147  }
148
149  @SuppressWarnings("EnumSwitchStatementWhichMissesCases")
150  @Override
151  @Metadata
152  public CapabilityStatement getServerConformance(HttpServletRequest theRequest, RequestDetails theRequestDetails) {
153
154    RestfulServerConfiguration configuration = getServerConfiguration(theRequestDetails);
155    Bindings bindings = configuration.provideBindings();
156
157    CapabilityStatement retVal = new CapabilityStatement();
158
159    retVal.setPublisher(myPublisher);
160    retVal.setDateElement(conformanceDate(theRequestDetails));
161    retVal.setFhirVersion(Enumerations.FHIRVersion.fromCode(FhirVersionEnum.R4.getFhirVersionString()));
162
163    ServletContext servletContext = (ServletContext) (theRequest == null ? null : theRequest.getAttribute(RestfulServer.SERVLET_CONTEXT_ATTRIBUTE));
164    String serverBase = configuration.getServerAddressStrategy().determineServerBase(servletContext, theRequest);
165    retVal
166      .getImplementation()
167      .setUrl(serverBase)
168      .setDescription(configuration.getImplementationDescription());
169
170    retVal.setKind(CapabilityStatementKind.INSTANCE);
171    retVal.getSoftware().setName(configuration.getServerName());
172    retVal.getSoftware().setVersion(configuration.getServerVersion());
173    retVal.addFormat(Constants.CT_FHIR_XML_NEW);
174    retVal.addFormat(Constants.CT_FHIR_JSON_NEW);
175    retVal.setStatus(PublicationStatus.ACTIVE);
176
177    CapabilityStatementRestComponent rest = retVal.addRest();
178    rest.setMode(RestfulCapabilityMode.SERVER);
179
180    Set<SystemRestfulInteraction> systemOps = new HashSet<>();
181    Set<String> operationNames = new HashSet<>();
182
183    Map<String, List<BaseMethodBinding<?>>> resourceToMethods = configuration.collectMethodBindings();
184    Map<String, Class<? extends IBaseResource>> resourceNameToSharedSupertype = configuration.getNameToSharedSupertype();
185    for (Entry<String, List<BaseMethodBinding<?>>> nextEntry : resourceToMethods.entrySet()) {
186
187      if (nextEntry.getKey().isEmpty() == false) {
188        Set<TypeRestfulInteraction> resourceOps = new HashSet<>();
189        CapabilityStatementRestResourceComponent resource = rest.addResource();
190        String resourceName = nextEntry.getKey();
191        
192        RuntimeResourceDefinition def;
193        FhirContext context = configuration.getFhirContext();
194        if (resourceNameToSharedSupertype.containsKey(resourceName)) {
195          def = context.getResourceDefinition(resourceNameToSharedSupertype.get(resourceName));
196        } else {
197          def = context.getResourceDefinition(resourceName);
198        }
199        resource.getTypeElement().setValue(def.getName());
200        resource.getProfileElement().setValue((def.getResourceProfile(serverBase)));
201
202        TreeSet<String> includes = new TreeSet<>();
203
204        // Map<String, CapabilityStatement.RestResourceSearchParam> nameToSearchParam = new HashMap<String,
205        // CapabilityStatement.RestResourceSearchParam>();
206        for (BaseMethodBinding<?> nextMethodBinding : nextEntry.getValue()) {
207          nextMethodBinding.getRestOperationType();
208          String resOpCode = nextMethodBinding.getRestOperationType().getCode();
209          if (resOpCode != null) {
210            TypeRestfulInteraction resOp;
211            try {
212              resOp = TypeRestfulInteraction.fromCode(resOpCode);
213            } catch (Exception e) {
214              resOp = null;
215            }
216            if (resOp != null) {
217              if (resourceOps.contains(resOp) == false) {
218                resourceOps.add(resOp);
219                resource.addInteraction().setCode(resOp);
220              }
221              if ("vread".equals(resOpCode)) {
222                // vread implies read
223                resOp = TypeRestfulInteraction.READ;
224                if (resourceOps.contains(resOp) == false) {
225                  resourceOps.add(resOp);
226                  resource.addInteraction().setCode(resOp);
227                }
228              }
229
230              if (nextMethodBinding.isSupportsConditional()) {
231                switch (resOp) {
232                  case CREATE:
233                    resource.setConditionalCreate(true);
234                    break;
235                  case DELETE:
236                    if (nextMethodBinding.isSupportsConditionalMultiple()) {
237                      resource.setConditionalDelete(ConditionalDeleteStatus.MULTIPLE);
238                    } else {
239                      resource.setConditionalDelete(ConditionalDeleteStatus.SINGLE);
240                    }
241                    break;
242                  case UPDATE:
243                    resource.setConditionalUpdate(true);
244                    break;
245                  default:
246                    break;
247                }
248              }
249            }
250          }
251
252          checkBindingForSystemOps(rest, systemOps, nextMethodBinding);
253
254          if (nextMethodBinding instanceof SearchMethodBinding) {
255            SearchMethodBinding methodBinding = (SearchMethodBinding) nextMethodBinding;
256            if (methodBinding.getQueryName() != null) {
257              String queryName = bindings.getNamedSearchMethodBindingToName().get(methodBinding);
258              if (operationNames.add(queryName)) {
259                rest.addOperation().setName(methodBinding.getQueryName()).setDefinition((getOperationDefinitionPrefix(theRequestDetails) + "OperationDefinition/" + queryName));
260              }
261            } else {
262              handleNamelessSearchMethodBinding(resource, def, includes, (SearchMethodBinding) nextMethodBinding, theRequestDetails);
263            }
264          } else if (nextMethodBinding instanceof OperationMethodBinding) {
265            OperationMethodBinding methodBinding = (OperationMethodBinding) nextMethodBinding;
266            String opName = bindings.getOperationBindingToName().get(methodBinding);
267            if (operationNames.add(opName)) {
268              // Only add each operation (by name) once
269              rest.addOperation().setName(methodBinding.getName().substring(1)).setDefinition((getOperationDefinitionPrefix(theRequestDetails) + "OperationDefinition/" + opName));
270            }
271          }
272
273          resource.getInteraction().sort(new Comparator<ResourceInteractionComponent>() {
274            @Override
275            public int compare(ResourceInteractionComponent theO1, ResourceInteractionComponent theO2) {
276              TypeRestfulInteraction o1 = theO1.getCode();
277              TypeRestfulInteraction o2 = theO2.getCode();
278              if (o1 == null && o2 == null) {
279                return 0;
280              }
281              if (o1 == null) {
282                return 1;
283              }
284              if (o2 == null) {
285                return -1;
286              }
287              return o1.ordinal() - o2.ordinal();
288            }
289          });
290
291        }
292
293        for (String nextInclude : includes) {
294          resource.addSearchInclude(nextInclude);
295        }
296      } else {
297        for (BaseMethodBinding<?> nextMethodBinding : nextEntry.getValue()) {
298          checkBindingForSystemOps(rest, systemOps, nextMethodBinding);
299          if (nextMethodBinding instanceof OperationMethodBinding) {
300            OperationMethodBinding methodBinding = (OperationMethodBinding) nextMethodBinding;
301            String opName = bindings.getOperationBindingToName().get(methodBinding);
302            if (operationNames.add(opName)) {
303              ourLog.debug("Found bound operation: {}", opName);
304              rest.addOperation().setName(methodBinding.getName().substring(1)).setDefinition((getOperationDefinitionPrefix(theRequestDetails) + "OperationDefinition/" + opName));
305            }
306          }
307        }
308      }
309    }
310
311    return retVal;
312  }
313
314  protected String getOperationDefinitionPrefix(RequestDetails theRequestDetails) {
315    if (theRequestDetails == null) {
316      return "";
317    }
318    return theRequestDetails.getServerBaseForRequest() + "/";
319  }
320
321  private void handleNamelessSearchMethodBinding(CapabilityStatementRestResourceComponent resource, RuntimeResourceDefinition def, TreeSet<String> includes,
322                                                 SearchMethodBinding searchMethodBinding, RequestDetails theRequestDetails) {
323    includes.addAll(searchMethodBinding.getIncludes());
324
325    List<IParameter> params = searchMethodBinding.getParameters();
326    List<SearchParameter> searchParameters = new ArrayList<>();
327    for (IParameter nextParameter : params) {
328      if ((nextParameter instanceof SearchParameter)) {
329        searchParameters.add((SearchParameter) nextParameter);
330      }
331    }
332    sortSearchParameters(searchParameters);
333    if (!searchParameters.isEmpty()) {
334
335      for (SearchParameter nextParameter : searchParameters) {
336
337        if (nextParameter.getParamType() == null) {
338          ourLog.warn("SearchParameter {}:{} does not declare a type - Not exporting in CapabilityStatement", def.getName(), nextParameter.getName());
339          continue;
340        }
341
342        String nextParamName = nextParameter.getName();
343
344        String nextParamUnchainedName = nextParamName;
345        if (nextParamName.contains(".")) {
346          nextParamUnchainedName = nextParamName.substring(0, nextParamName.indexOf('.'));
347        }
348
349        String nextParamDescription = nextParameter.getDescription();
350
351        /*
352         * If the parameter has no description, default to the one from the resource
353         */
354        if (StringUtils.isBlank(nextParamDescription)) {
355          RuntimeSearchParam paramDef = def.getSearchParam(nextParamUnchainedName);
356          if (paramDef != null) {
357            nextParamDescription = paramDef.getDescription();
358          }
359        }
360
361
362        CapabilityStatementRestResourceSearchParamComponent param = resource.addSearchParam();
363        String typeCode = nextParameter.getParamType().getCode();
364        param.getTypeElement().setValueAsString(typeCode);
365        param.setName(nextParamUnchainedName);
366        param.setDocumentation(nextParamDescription);
367
368      }
369    }
370  }
371
372
373  @Read(type = OperationDefinition.class)
374  public OperationDefinition readOperationDefinition(@IdParam IdType theId, RequestDetails theRequestDetails) {
375    if (theId == null || theId.hasIdPart() == false) {
376      throw new ResourceNotFoundException(theId);
377    }
378    RestfulServerConfiguration configuration = getServerConfiguration(theRequestDetails);
379    Bindings bindings = configuration.provideBindings();
380
381    List<OperationMethodBinding> operationBindings = bindings.getOperationNameToBindings().get(theId.getIdPart());
382    if (operationBindings != null && !operationBindings.isEmpty()) {
383      return readOperationDefinitionForOperation(operationBindings);
384    }
385    List<SearchMethodBinding> searchBindings = bindings.getSearchNameToBindings().get(theId.getIdPart());
386    if (searchBindings != null && !searchBindings.isEmpty()) {
387      return readOperationDefinitionForNamedSearch(searchBindings);
388    }
389    throw new ResourceNotFoundException(theId);
390  }
391
392  private OperationDefinition readOperationDefinitionForNamedSearch(List<SearchMethodBinding> bindings) {
393    OperationDefinition op = new OperationDefinition();
394    op.setStatus(PublicationStatus.ACTIVE);
395    op.setKind(OperationKind.QUERY);
396    op.setAffectsState(false);
397
398    op.setSystem(false);
399    op.setType(false);
400    op.setInstance(false);
401
402    Set<String> inParams = new HashSet<>();
403
404    for (SearchMethodBinding binding : bindings) {
405      if (isNotBlank(binding.getDescription())) {
406        op.setDescription(binding.getDescription());
407      }
408      if (isBlank(binding.getResourceProviderResourceName())) {
409        op.setSystem(true);
410      } else {
411        op.setType(true);
412        op.addResourceElement().setValue(binding.getResourceProviderResourceName());
413      }
414      op.setCode(binding.getQueryName());
415      for (IParameter nextParamUntyped : binding.getParameters()) {
416        if (nextParamUntyped instanceof SearchParameter) {
417          SearchParameter nextParam = (SearchParameter) nextParamUntyped;
418          if (!inParams.add(nextParam.getName())) {
419            continue;
420          }
421          OperationDefinitionParameterComponent param = op.addParameter();
422          param.setUse(OperationParameterUse.IN);
423          param.setType("string");
424          param.getSearchTypeElement().setValueAsString(nextParam.getParamType().getCode());
425          param.setMin(nextParam.isRequired() ? 1 : 0);
426          param.setMax("1");
427          param.setName(nextParam.getName());
428        }
429      }
430
431      if (isBlank(op.getName())) {
432        if (isNotBlank(op.getDescription())) {
433          op.setName(op.getDescription());
434        } else {
435          op.setName(op.getCode());
436        }
437      }
438    }
439
440    return op;
441  }
442
443  private OperationDefinition readOperationDefinitionForOperation(List<OperationMethodBinding> bindings) {
444    OperationDefinition op = new OperationDefinition();
445    op.setStatus(PublicationStatus.ACTIVE);
446    op.setKind(OperationKind.OPERATION);
447    op.setAffectsState(false);
448
449    // We reset these to true below if we find a binding that can handle the level
450    op.setSystem(false);
451    op.setType(false);
452    op.setInstance(false);
453
454    Set<String> inParams = new HashSet<>();
455    Set<String> outParams = new HashSet<>();
456
457    for (OperationMethodBinding sharedDescription : bindings) {
458      if (isNotBlank(sharedDescription.getDescription())) {
459        op.setDescription(sharedDescription.getDescription());
460      }
461      if (sharedDescription.isCanOperateAtInstanceLevel()) {
462        op.setInstance(true);
463      }
464      if (sharedDescription.isCanOperateAtServerLevel()) {
465        op.setSystem(true);
466      }
467      if (sharedDescription.isCanOperateAtTypeLevel()) {
468        op.setType(true);
469      }
470      if (!sharedDescription.isIdempotent()) {
471        op.setAffectsState(!sharedDescription.isIdempotent());
472      }
473      op.setCode(sharedDescription.getName().substring(1));
474      if (sharedDescription.isCanOperateAtInstanceLevel()) {
475        op.setInstance(sharedDescription.isCanOperateAtInstanceLevel());
476      }
477      if (sharedDescription.isCanOperateAtServerLevel()) {
478        op.setSystem(sharedDescription.isCanOperateAtServerLevel());
479      }
480      if (isNotBlank(sharedDescription.getResourceName())) {
481        op.addResourceElement().setValue(sharedDescription.getResourceName());
482      }
483
484      for (IParameter nextParamUntyped : sharedDescription.getParameters()) {
485        if (nextParamUntyped instanceof OperationParameter) {
486          OperationParameter nextParam = (OperationParameter) nextParamUntyped;
487          OperationDefinitionParameterComponent param = op.addParameter();
488          if (!inParams.add(nextParam.getName())) {
489            continue;
490          }
491          param.setUse(OperationParameterUse.IN);
492          if (nextParam.getParamType() != null) {
493            param.setType(nextParam.getParamType());
494          }
495          if (nextParam.getSearchParamType() != null) {
496            param.getSearchTypeElement().setValueAsString(nextParam.getSearchParamType());
497          }
498          param.setMin(nextParam.getMin());
499          param.setMax(nextParam.getMax() == -1 ? "*" : Integer.toString(nextParam.getMax()));
500          param.setName(nextParam.getName());
501        }
502      }
503
504      for (ReturnType nextParam : sharedDescription.getReturnParams()) {
505        if (!outParams.add(nextParam.getName())) {
506          continue;
507        }
508        OperationDefinitionParameterComponent param = op.addParameter();
509        param.setUse(OperationParameterUse.OUT);
510        if (nextParam.getType() != null) {
511          param.setType(nextParam.getType());
512        }
513        param.setMin(nextParam.getMin());
514        param.setMax(nextParam.getMax() == -1 ? "*" : Integer.toString(nextParam.getMax()));
515        param.setName(nextParam.getName());
516      }
517    }
518
519    if (isBlank(op.getName())) {
520      if (isNotBlank(op.getDescription())) {
521        op.setName(op.getDescription());
522      } else {
523        op.setName(op.getCode());
524      }
525    }
526
527    if (op.hasSystem() == false) {
528      op.setSystem(false);
529    }
530    if (op.hasInstance() == false) {
531      op.setInstance(false);
532    }
533
534    return op;
535  }
536
537  /**
538   * Sets the cache property (default is true). If set to true, the same response will be returned for each invocation.
539   * <p>
540   * See the class documentation for an important note if you are extending this class
541   * </p>
542   *
543   * @deprecated Since 4.0.0 - This method no longer does anything
544   */
545  @Deprecated
546  public ServerCapabilityStatementProvider setCache(boolean theCache) {
547    return this;
548  }
549
550  @Override
551  public void setRestfulServer(RestfulServer theRestfulServer) {
552    // ignore
553  }
554
555  private void sortSearchParameters(List<SearchParameter> searchParameters) {
556    Collections.sort(searchParameters, new Comparator<SearchParameter>() {
557      @Override
558      public int compare(SearchParameter theO1, SearchParameter theO2) {
559        if (theO1.isRequired() == theO2.isRequired()) {
560          return theO1.getName().compareTo(theO2.getName());
561        }
562        if (theO1.isRequired()) {
563          return -1;
564        }
565        return 1;
566      }
567    });
568  }
569}