/*******************************************************************************
* Copyright (c) 2008 SAP
* see https://research.qkal.sap.corp/mediawiki/index.php/CoMONET
*
* Date: $Date: 2009-08-30 09:59:50 +0200 (So, 30 Aug 2009) $
* Revision: $Revision: 7772 $
* Author: $Author: c5127705 $
*******************************************************************************/
package com.sap.furcas.runtime.parser;
import java.util.List;
import com.sap.furcas.runtime.parser.impl.DelayedReference;
import com.sap.furcas.runtime.parser.impl.ModelElementProxy;
import com.sap.furcas.runtime.parser.impl.ObservableInjectingParser;
import com.sap.furcas.runtime.parser.impl.context.ContextManager;
/**
* A model Injector supports the process of parsing a DSL sample into a DSL
* Model. It may use an IModelAdapter to create / update / delete ModelElements,
* but also needs to deal with setting References and collecting and reporting
* Errors. For Errors, it also has to maintain Token locations for Model
* Elements derived from tokens.
*
* This interface is used in generated parsers to launch model creation or error
* occurrence actions. This package already ships with a default ModelInjector
* which should serve all purposes, so this class does not need subclassing in
* general.
*/
public interface IModelInjector extends IInjectionHelper {
/**
* creates a model element of the given typename. In case of error, no
* exception is expected, but rather an error added to the error list.
*
* @param name
* @param context
* @param addToContext
* @return
* @throws ModelElementCreationException
*/
Object createOrResolve(ModelElementProxy proxy, ANTLR3LocationToken firstToken,
ANTLR3LocationToken lastToken) throws ModelElementCreationException;
/**
* creates or returns the enum literal of the given enumeration.
*
* @param enumName
* @param name
* @return
*/
Object createEnumLiteral(List<String> enumName, String name);
/**
* sets a named feature of a modelelement to some value, which might also be
* a modelElement.
*
* @param modelElement
* @param prop
* @param value
*/
void set(Object modelElement, String prop, Object value);
/**
* sets a named feature of a modelelement to some value, which might also be
* a modelElement. Additionally an index may be provided that indicates at
* which position within an ordered property the value should be added.
*
* @param modelElement
* @param prop
* @param value
* @param index
*/
void set(Object modelElement, String prop, Object value, int index);
/**
* Used to remove the <tt>value</tt> from the given property of the
* <tt>modelElement</tt>.
*
* @param modelElement
* @param propertyName
* @param value
*/
void unset(Object modelElement, String propertyName, Object value);
void setCommentsAfter(Object ret, org.antlr.runtime.TokenStream stream,
org.antlr.runtime.Token nextToken);
void setCommentsBefore(Object ret, org.antlr.runtime.TokenStream stream,
org.antlr.runtime.Token firstToken);
/**
* unescapes the String and removes delimiters from both ends, such as ".
*
* @param text
* @param delimLength
* @return
* @deprecated use lexers own unescapeString method instead.
*/
@Deprecated
String unescapeString(String text, int delimLength);
/**
* performs delayed actions on the adapter (usually like delayed creation
* until more properties are known).
*/
void performAdapterDeferredActions();
/**
* resolves a reference using the context map as In-Text scope, may create
* elements to reference, and throw exceptions when that fails.
*
* @param reference
* @return <code>true</code> if the reference was resolved successfully,
* <code>false</code> else.
* @throws ModelElementCreationException
*/
boolean resolveReference(DelayedReference reference,
ContextManager contextManager, ObservableInjectingParser parser) throws ModelElementCreationException;
// TODO: use primitives instead?
/**
* Returns the {@link IModelAdapter} that is used by this injector.
*/
IModelAdapter getModelAdapter();
}