001package ca.uhn.fhir.rest.server;
002
003import java.util.Date;
004
005/*
006 * #%L
007 * HAPI FHIR - Core Library
008 * %%
009 * Copyright (C) 2014 - 2017 University Health Network
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
025import java.util.List;
026
027import org.hl7.fhir.instance.model.api.IBaseResource;
028import org.hl7.fhir.instance.model.api.IPrimitiveType;
029
030import ca.uhn.fhir.model.primitive.InstantDt;
031
032public interface IBundleProvider {
033
034        /**
035         * Load the given collection of resources by index, plus any additional resources per the
036         * server's processing rules (e.g. _include'd resources, OperationOutcome, etc.). For example,
037         * if the method is invoked with index 0,10 the method might return 10 search results, plus an
038         * additional 20 resources which matched a client's _include specification.
039         * 
040         * @param theFromIndex
041         *           The low index (inclusive) to return
042         * @param theToIndex
043         *           The high index (exclusive) to return
044         * @return A list of resources. The size of this list must be at least <code>theToIndex - theFromIndex</code>.
045         */
046        List<IBaseResource> getResources(int theFromIndex, int theToIndex);
047
048        /**
049         * Optionally may be used to signal a preferred page size to the server, e.g. because
050         * the implementing code recognizes that the resources which will be returned by this
051         * implementation are expensive to load so a smaller page size should be used. The value
052         * returned by this method will only be used if the client has not explicitly requested
053         * a page size.
054         * 
055         * @return Returns the preferred page size or <code>null</code>
056         */
057        Integer preferredPageSize();
058
059        /**
060         * Returns the total number of results which match the given query (exclusive of any
061         * _include's or OperationOutcome). May return {@literal null} if the total size is not
062         * known or would be too expensive to calculate.
063         */
064        Integer size();
065
066        /**
067         * Returns the instant as of which this result was valid
068         */
069        IPrimitiveType<Date> getPublished();
070
071        /**
072         * Returns the UUID associated with this search. Note that this
073         * does not need to return a non-null value unless it a
074         * {@link IPagingProvider} is being used that requires UUIDs
075         * being returned.
076         * <p>
077         * In other words, if you are using the default {@link FifoMemoryPagingProvider} in
078         * your server, it is fine for this method to simply return {@code null} since {@link FifoMemoryPagingProvider}
079         * does not use the value anyhow. On the other hand, if you are creating a custom
080         * [@code IPagingProvider} implementation you might use this method to communicate
081         * the search ID back to the provider.
082         * </p>
083         */
084        public String getUuid();
085
086}