001/*
002 *  Copyright 2018 Anyware Services
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.ametys.plugins.repository.data.holder.group;
017
018import java.io.IOException;
019import java.util.List;
020
021import org.xml.sax.ContentHandler;
022import org.xml.sax.SAXException;
023
024import org.ametys.plugins.repository.data.holder.DataHolder;
025import org.ametys.plugins.repository.data.holder.group.impl.ModifiableModelAwareRepeater;
026import org.ametys.plugins.repository.data.repositorydata.RepositoryData;
027import org.ametys.runtime.model.exception.BadItemTypeException;
028import org.ametys.runtime.model.exception.UndefinedItemPathException;
029import org.ametys.runtime.model.type.DataContext;
030
031/**
032 * Interface for repeaters
033 */
034public interface Repeater
035{
036    /**
037     * Retrieves the repeater entries, sorted by position
038     * @return the repeater entries
039     */
040    public List<? extends RepeaterEntry> getEntries();
041    
042    /**
043     * Retrieves the repeater entry at the given position. The position starts at index 1.
044     * The position can be an integer between 1 and the repeater size to get an entry from the beginning
045     * Or the position can an integer between 0 and - the repeater size to get an entry from the end (0 means at the end, -1 means before the last one and so on)
046     * @param position the position of the entry to retrieve
047     * @return the repeater entry, <code>null</code> if there is no entry at this position
048     */
049    public RepeaterEntry getEntry(int position);
050    
051    /**
052     * Retrieves the size of the repeater
053     * @return the size of the repeater
054     */
055    public int getSize();
056    
057    /**
058     * Determines if the repeater has an entry at the given position. The position starts at index 1.
059     * The position can be an integer between 1 and the repeater size to get an entry from the beginning
060     * Or the position can an integer between 0 and - the repeater size to get an entry from the end (0 means at the end, -1 means before the last one and so on)
061     * @param position the position
062     * @return <code>true</code> if the repeater has an entry at the given position, <code>false</code> otherwise
063     */
064    public boolean hasEntry(int position);
065    
066    /**
067     * Copies the current {@link Repeater} to the given {@link ModifiableRepeater}.
068     * @param repeater The destination repeater. Can not be null.
069     * @throws UndefinedItemPathException if one of the copied data is not defined by the model of the destination {@link ModifiableModelAwareRepeater}
070     * @throws BadItemTypeException if the type defined by the model of the destination {@link ModifiableModelAwareRepeater} doesn't match the copied value
071     */
072    public void copyTo(ModifiableRepeater repeater) throws UndefinedItemPathException, BadItemTypeException;
073    
074    /**
075     * Generates SAX events for the data at the given data path in the current {@link DataHolder}
076     * Do not generate any event if there is no values at the given path
077     * @param contentHandler the {@link ContentHandler} that will receive the SAX events
078     * @param dataPath the path of the data to SAX
079     * @throws SAXException if an error occurs during the SAX events generation
080     * @throws IOException if an error occurs while reading a value using the I/O API
081     */
082    public default void dataToSAX(ContentHandler contentHandler, String dataPath) throws SAXException, IOException
083    {
084        dataToSAX(contentHandler, dataPath, DataContext.newInstance());
085    }
086    
087    /**
088     * Generates SAX events for the data at the given data path in the current {@link DataHolder}
089     * Do not generate any event if there is no values at the given path
090     * @param contentHandler the {@link ContentHandler} that will receive the SAX events
091     * @param dataPath the path of the data to SAX
092     * @param context The context of the data to SAX
093     * @throws SAXException if an error occurs during the SAX events generation
094     * @throws IOException if an error occurs while reading a value using the I/O API
095     */
096    public void dataToSAX(ContentHandler contentHandler, String dataPath, DataContext context) throws SAXException, IOException;
097    
098    /**
099     * Retrieves the repository data used by this {@link Repeater}
100     * @return the repository data used by this {@link Repeater}
101     */
102    public RepositoryData getRepositoryData();
103    
104    /**
105     * Retrieves the parent of the current {@link Repeater}
106     * @return the parent of the current {@link Repeater}
107     */
108    public DataHolder getParentDataHolder();
109    
110    /**
111     * Retrieves the root {@link DataHolder} of the current repeater
112     * @return the root {@link DataHolder}
113     */
114    public DataHolder getRootDataHolder();
115}