/*
 * 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 freemarker.template;

import java.util.Iterator;
import java.util.NoSuchElementException;

Adds key-value pair listing capability to TemplateHashModelEx. While in many cases that can also be achieved with TemplateHashModelEx.keys() and then TemplateHashModel.get(String), that has some problems. One is that TemplateHashModel.get(String) only accepts string keys, while TemplateHashModelEx.keys() can return non-string keys too. The other is that calling TemplateHashModelEx.keys() and then TemplateHashModel.get(String) for each key can be slower than listing the key-value pairs in one go. 
Since:
2.3.25/**
 * Adds key-value pair listing capability to {@link TemplateHashModelEx}. While in many cases that can also be achieved
 * with {@link #keys()} and then {@link #get(String)}, that has some problems. One is that {@link #get(String)} only
 * accepts string keys, while {@link #keys()} can return non-string keys too. The other is that calling {@link #keys()}
 * and then {@link #get(String)} for each key can be slower than listing the key-value pairs in one go.
 * 
 * @since 2.3.25
 */
public interface TemplateHashModelEx2 extends TemplateHashModelEx {

    
Returns:
The iterator that walks through the key-value pairs in the hash. Not null./**
     * @return The iterator that walks through the key-value pairs in the hash. Not {@code null}. 
     */
    KeyValuePairIterator keyValuePairIterator() throws TemplateModelException;
    
    
A key-value pair in a hash; used for KeyValuePairIterator. 
Since:
2.3.25/**
     * A key-value pair in a hash; used for {@link KeyValuePairIterator}.
     *  
     * @since 2.3.25
     */
    interface KeyValuePair {
        
        
Returns:
Any type of TemplateModel, maybe null (if the hash entry key is null)./**
         * @return Any type of {@link TemplateModel}, maybe {@code null} (if the hash entry key is {@code null}).
         */
        TemplateModel getKey() throws TemplateModelException;
        
        
Returns:
Any type of TemplateModel, maybe null (if the hash entry value is null)./**
         * @return Any type of {@link TemplateModel}, maybe {@code null} (if the hash entry value is {@code null}).
         */
        TemplateModel getValue() throws TemplateModelException;
    }
    
    
Iterates over the key-value pairs in a hash. This is very similar to an Iterator, but has a fixed item type, can throw TemplateModelException-s, and has no remove() method. 
Since:
2.3.25/**
     * Iterates over the key-value pairs in a hash. This is very similar to an {@link Iterator}, but has a fixed item
     * type, can throw {@link TemplateModelException}-s, and has no {@code remove()} method. 
     *
     * @since 2.3.25
     */
    interface KeyValuePairIterator {
        
        
Similar to Iterator.hasNext(). /**
         * Similar to {@link Iterator#hasNext()}.
         */
        boolean hasNext() throws TemplateModelException;
        
        
Similar to Iterator.next(). 
Throws:
NoSuchElementException – 
Returns:
Not null/**
         * Similar to {@link Iterator#next()}.
         * 
         * @return Not {@code null}
         * 
         * @throws NoSuchElementException
         */
        KeyValuePair next() throws TemplateModelException;
    }
    
}