001/* ***** BEGIN LICENSE BLOCK *****
002 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
003 *
004 * The contents of this file are subject to the Mozilla Public License Version
005 * 1.1 (the "License"); you may not use this file except in compliance with
006 * the License. You may obtain a copy of the License at
007 * http://www.mozilla.org/MPL/
008 *
009 * Software distributed under the License is distributed on an "AS IS" basis,
010 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
011 * for the specific language governing rights and limitations under the
012 * License.
013 *
014 * The Original Code is part of dcm4che, an implementation of DICOM(TM) in
015 * Java(TM), hosted at https://github.com/gunterze/dcm4che.
016 *
017 * The Initial Developer of the Original Code is
018 * Agfa Healthcare.
019 * Portions created by the Initial Developer are Copyright (C) 2015
020 * the Initial Developer. All Rights Reserved.
021 *
022 * Contributor(s):
023 * See @authors listed below
024 *
025 * Alternatively, the contents of this file may be used under the terms of
026 * either the GNU General Public License Version 2 or later (the "GPL"), or
027 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
028 * in which case the provisions of the GPL or the LGPL are applicable instead
029 * of those above. If you wish to allow use of your version of this file only
030 * under the terms of either the GPL or the LGPL, and not to allow others to
031 * use your version of this file under the terms of the MPL, indicate your
032 * decision by deleting the provisions above and replace them with the notice
033 * and other provisions required by the GPL or the LGPL. If you do not delete
034 * the provisions above, a recipient may use your version of this file under
035 * the terms of any one of the MPL, the GPL or the LGPL.
036 *
037 * ***** END LICENSE BLOCK ***** */
038package org.dcm4che3.conf.api;
039
040import org.dcm4che3.conf.core.api.ConfigurationException;
041import org.dcm4che3.net.ApplicationEntity;
042import org.dcm4che3.net.Device;
043
044import java.util.List;
045
046/**
047 * This interface should be used by vendors/integrators to access and manipulate the DICOM configuration in a type-safe way.
048 * Always give the preference to this interface when possible.
049 *
050 * @author Gunter Zeilinger <gunterze@gmail.com>
051 * @author Roman K
052 */
053public interface DicomConfiguration {
054
055    /**
056     * Looks up an application entity by name
057     * @param aet application entity name
058     * @return
059     * @throws org.dcm4che3.conf.core.api.ConfigurationException
060     */
061    ApplicationEntity findApplicationEntity(String aet) throws ConfigurationException;
062
063    /**
064     * Looks up an application entity by UUID
065     * @param uuid UUID
066     * @return
067     * @throws org.dcm4che3.conf.core.api.ConfigurationException
068     */
069    ApplicationEntity findApplicationEntityByUUID(String uuid) throws ConfigurationException;
070
071    /**
072     * Looks up a device by UUID
073     * @param uuid UUID
074     * @return
075     * @throws org.dcm4che3.conf.core.api.ConfigurationException
076     */
077    Device findDeviceByUUID(String uuid) throws ConfigurationException;
078
079    /**
080     * Looks up a device by name
081     * @param name device name
082     * @return
083     * @throws org.dcm4che3.conf.core.api.ConfigurationException
084     */
085    Device findDevice(String name) throws ConfigurationException;
086
087    /**
088     * Stores the full configuration of a device in the configuration backend.
089     * @param device Device to store
090     * @throws ConfigurationAlreadyExistsException When a device with such name already exists.
091     * @throws ConfigurationException When an error occured during the operation
092     */
093    void persist(Device device) throws ConfigurationException;
094
095    /**
096     * Replaces the full configuration of a device in the configuration backend with the configuration of
097     * the provided device. The behavior is similar to JPA's merge.
098     * @param device Device to merge
099     * @throws ConfigurationException When an error occured during the operation
100     */
101    void merge(Device device) throws ConfigurationException;
102
103    /**
104     * Removes the device and its configuration from the configuration storage fully.
105     * @param name
106     * @throws ConfigurationException
107     */
108    void removeDevice(String name) throws ConfigurationException;
109
110    /**
111     * Returns all device names from the configuration backend
112     * @return Device names
113     * @throws ConfigurationException
114     */
115    String[] listDeviceNames() throws ConfigurationException;
116
117    /**
118     * Returns all AE names from all devices from the configuration backend
119     * @return AE names
120     * @throws org.dcm4che3.conf.core.api.ConfigurationException
121     */
122    List<String> listAllAETitles() throws ConfigurationException;
123
124    /**
125     * Invalidates any present cached state for the configuration storage view of the client.
126     * There is no guarantee whether the devices accessed afterwards will be re-loaded lazily or eagerly.
127     *
128     * Has no effect for non-cached or consistently-cached configuration storage backends.
129     */
130    void sync() throws ConfigurationException;
131
132
133    /**
134     * Get an extension of configuration
135     * @param clazz Extension class
136     * @param <T>
137     * @throws IllegalArgumentException - in case an extension of specified class is nto found
138     * @return
139     */
140    <T> T getDicomConfigurationExtension(Class<T> clazz);
141    
142    /**
143     * Provides support for batching configuration changes.
144     * </p>
145     * It is guaranteed that
146     * <ul>
147     * <li>All configuration reads and writes in a batch are performed within a single transaction, i.e. the changes are atomic and performed in READ COMMITTED isolation</li>
148     * <li>When this method is called, an ongoing transaction (in case there is one) will be SUSPENDED. The batch will ALWAYS be executed in a SEPARATE transaction.</li>
149     * <li>At most ONE batch is executed at the same time in the whole cluster (synchronized with a database lock)</li>
150     * </ul>
151     * 
152     * @param dicomConfigBatch Configuration batch to execute
153     */
154    void runBatch(DicomConfigBatch dicomConfigBatch);
155    
156    /**
157     * Defines a configuration batch that allows to execute configuration changes in a bulk-type manner.
158     * 
159     * @author Alexander Hoermandinger <alexander.hoermandinger@agfa.com>
160     */
161    interface DicomConfigBatch {
162        /**
163         * Executes configuration batch changes on the specified DICOM configuration.
164         */
165        void run();
166    }
167    
168}