/*
 *  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.
 *  
 *  $Rev$  $Date$
 */
package test.sdo21.framework;

import java.io.InputStream;
import java.io.ObjectInputStream;
import java.io.ObjectOutputStream;
import java.io.OutputStream;
import java.util.Collection;

import test.sdo21.tests.ConsistencyTestTemplate;
import test.sdo21.tests.TestData.StandardDynamicFactory;
import test.sdo21.tests.TestData.StandardFactory;
import test.sdo21.tests.TestData.StandardXSDFactory;
import test.sdo21.tests.TestData.TestDataFactory;
import test.sdo21.tests.util.CTSUtil;

import commonj.sdo.DataGraph;
import commonj.sdo.DataObject;
import commonj.sdo.Type;
import commonj.sdo.helper.HelperContext;

/**
 * Vendors can provide an implementation of this interface to bootstrap their
 * SDO implementation.
 */
public interface TestHelper {

    public static final String INCOMPLETE_TEST_CASE_FAILURE = "The following test case is incomplete";

    /**
     * Initialize the SDO implementation being tests.
     */
    public void init();

    /**
     * Returns collection containing DataObject, String pairs to be used as
     * arguments to paramatized test cases. DataObjects should adhere to
     * api_test.xsd and should be populated. The String should be a description
     * of the mechanism used to create and populate the DataObject. 
     * 
     * @deprecated @see {@link ConsistencyTestTemplate}
     */
    public Collection getParamatizedDataObject();

    /**
     * Convenience method for creating a type definition.
     * 
     * @param uri
     * @param name
     * @param helperContext
     * @return
     * @deprecated
     * @see CTSUtil
     */
    public DataObject createTypeDef(String uri, String name, boolean open, HelperContext helperContext);

    /**
     * Convenience method for creating a property definition
     * 
     * @param typeDef The type definition that this property should be added to
     * @param name The name for the property
     * @param type The type to assign to the property
     * @param isMany
     * @param isContainment
     * @return
     * @deprecated
     * @see CTSUtil
     */
    public DataObject createPropertyDef(DataObject typeDef,
                                        String name,
                                        Type type,
                                        boolean isMany,
                                        boolean isContainment);

    /**
     * Convenience method for creating a property definition
     * 
     * @param typeDef The type definition that this property should be added to
     * @param name The name for the property
     * @param type The type to assign to the property e.g.
     *            "commonj.sdo#DataObject"
     * @param isMany
     * @param isContainment
     * @param helperContext
     * @return
     * 
     * @deprecated
     * @see CTSUtil

     */
    public DataObject createPropertyDef(DataObject typeDef,
                                        String name,
                                        String type,
                                        boolean isMany,
                                        boolean isContainment,
                                        HelperContext helperContext);

    /**
     * Convenience method for creating a unique name that can be used for a
     * property or type.
     *
     * @return String containing a unique name
     * 
     * @deprecated
     * @see CTSUtil

     */
    public String createUniqueName();

    /**
     * Create an empty data graph.
     * 
     * @return the new data graph instance.
     */
    public DataGraph createDataGraph();

    /**
     * Create a new HelperContext, a new scope
     * 
     * @return the new HelperContext instance.
     */
    public HelperContext createHelperContext();

    /**
     * Create a new DataObjectFactory
     * 
     * @return the new DataObjectFactory instance.
     * @deprecated
     * @see TestDataFactory
     * @see StandardFactory
     * @see StandardDynamicFactory
     * @see StandardXSDFactory
     * 
     */
    public DataObjectFactory createDataObjectFactory(String factory,
    		                                      HelperContext helperContext);
       
    /**
     * @return Static SDO that adhere's to simple.xsd
    
    public DataObject getSimpleSDO();
    */
    /**
     * @return Static Quote SDO from simple.xsd defintion.
     
    public DataObject getSimpleQuoteSDO();
    */
    
    /**
     * Create a new ObjectOutputStream
     * 
     * @return the new ObjectOutputStream instance.
     */
    public ObjectOutputStream createObjectOutputStream(OutputStream os, 
                                                    HelperContext helperContext);

    /**
     * Create a new ObjectInutStream
     * 
     * @return the new ObjectInputStream instance.
     */
    public ObjectInputStream createObjectInputStream(InputStream is, 
                                                  HelperContext helperContext);
    
    /**
     * Serialize a DataObject using an XMLStreamHelper
     */
//    public void serializeViaXMLStreamHelper(TypeHelper typeHelper, 
//                             DataObject dataObject, 
//                             XMLStreamWriter serializer);
}