/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.jackrabbit.core.xml;
import org.apache.jackrabbit.core.NodeImpl;
import org.apache.jackrabbit.core.state.NodeState;
import javax.jcr.RepositoryException;
import javax.jcr.nodetype.ConstraintViolationException;
import java.util.List;
/**
* <code>ProtectedNodeImporter</code> provides means to import protected
* <code>Node</code>s and the subtree defined below such nodes.
* <p>
* The import of a protected tree is started by the <code>Importer</code> by
* calling {@link #start(NodeImpl)}. If the <code>ProtectedNodeImporter</code>
* is able to deal with that type of protected node, it is in charge of dealing
* with all subsequent child <code>NodeInfo</code>s present below the protected
* parent until {@link #end(NodeImpl)} is called. The latter resets this importer
* and makes it available for another protected import.
*/
public interface ProtectedNodeImporter extends ProtectedItemImporter {
/**
* Notifies this importer about the existence of a protected node that
* has either been created (NEW) or has been found to be existing.
* This importer implementation is in charge of evaluating the nature of
* that protected node in order to determine, if it is able to handle
* subsequent protected or non-protected child nodes in the tree below
* that parent.
*
* @param protectedParent A protected node that has either been created
* during the current XML import or that has been found to be existing
* without allowing same-name siblings.
* @return <code>true</code> If this importer is able to deal with the
* tree that may be present below the given protected Node.
* @throws IllegalStateException If this method is called on
* this importer without having reached {@link #end(NodeImpl)}.
* @throws RepositoryException If an error occurs.
*/
boolean start(NodeImpl protectedParent) throws IllegalStateException,
RepositoryException;
/**
* Notifies this importer about the existence of a protected node that
* has either been created (NEW) or has been found to be existing.
* This importer implementation is in charge of evaluating the nature of
* that protected node in order to determine, if it is able to handle
* subsequent protected or non-protected child nodes in the tree below
* that parent.
*
* @param protectedParent A protected node that has either been created
* during the current XML import or that has been found to be existing
* without allowing same-name siblings.
* @return <code>true</code> If this importer is able to deal with the
* tree that may be present below the given protected NodeState.
* @throws IllegalStateException If this method is called on
* this importer without having reached {@link #end(NodeState)}.
* @throws RepositoryException If an error occurs.
*/
boolean start(NodeState protectedParent) throws IllegalStateException,
RepositoryException;
/**
* Informs this importer that the tree to be imported below
* <code>protectedParent</code> has bee completed. This allows the importer
* to be reset in order to be able to deal with another call to
* {@link #start(NodeImpl)}.
* <p>
* If {@link #start(NodeImpl)} hasn't been called before, this method returns
* silently.
*
* @param protectedParent
* @throws IllegalStateException If end is called in an illegal state.
* @throws javax.jcr.nodetype.ConstraintViolationException If the tree
* that was imported is incomplete.
* @throws RepositoryException If another error occurs.
*/
void end(NodeImpl protectedParent) throws IllegalStateException,
ConstraintViolationException, RepositoryException;
/**
* Informs this importer that the tree to be imported below
* <code>protectedParent</code> has bee completed. This allows the importer
* to be reset in order to be able to deal with another call to
* {@link #start(NodeState)}.
* <p>
* If {@link #start(NodeState)} hasn't been called before, this method returns
* silently.
*
* @param protectedParent
* @throws IllegalStateException If end is called in an illegal state.
* @throws javax.jcr.nodetype.ConstraintViolationException If the tree
* that was imported is incomplete.
* @throws RepositoryException If another error occurs.
*/
void end(NodeState protectedParent) throws IllegalStateException,
ConstraintViolationException, RepositoryException;
/**
* Informs this importer about a new <code>childInfo</code> and it's properties.
* If the importer is able to successfully import the given information
* this method returns silently. Otherwise
* <code>ConstraintViolationException</code> is thrown, in which case the
* whole import fails.
* <p>
* In case this importer deals with multiple levels of nodes, it is in
* charge of maintaining the hierarchical structure (see also {#link endChildInfo()}.
* <p>
* If {@link #start(NodeImpl)} hasn't been called before, this method returns
* silently.
*
* @param childInfo
* @param propInfos
* @throws IllegalStateException If called in an illegal state.
* @throws javax.jcr.nodetype.ConstraintViolationException If the given
* infos contain invalid or incomplete data and therefore cannot be properly
* handled by this importer.
* @throws RepositoryException If another error occurs.
*/
void startChildInfo(NodeInfo childInfo, List<PropInfo> propInfos)
throws IllegalStateException, ConstraintViolationException, RepositoryException;
/**
* Informs this importer about the end of a child info.
* <p>
* If {@link #start(NodeImpl)} hasn't been called before, this method returns
* silently.
*
* @throws IllegalStateException If end is called in an illegal state.
* @throws javax.jcr.nodetype.ConstraintViolationException If this method
* is called before all required child information has been imported.
* @throws RepositoryException If another error occurs.
*/
void endChildInfo() throws RepositoryException;
}