atg.repository.xml

Class UpdateService

java.lang.Object

atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

atg.nucleus.GenericService

atg.repository.xml.ModifyService

atg.repository.xml.UpdateService

All Implemented Interfaces:

atg.core.logging.Logging, atg.core.logging.TraceLogging, atg.naming.AbsoluteNameable, NameContextBindingListener, NameContextElement, atg.naming.NameContextParentable, NameResolver, AdminableService, atg.nucleus.Configured, ApplicationLogging, atg.nucleus.logging.ApplicationLoggingSender, atg.nucleus.logging.TraceApplicationLogging, VariableArgumentApplicationLogging, ComponentNameResolver, Service, ServiceListener, java.util.EventListener, org.xml.sax.ErrorHandler

public class UpdateService
extends atg.repository.xml.ModifyService

Service class used by applications to update an item in a given repository. The item to update can either be passed to a method of this class, or selected out of the repository based upon a certain match criteria.

Applications are expected to call one of the updateItem() methods defined on this class.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CHECKOUT_TAG Tag supplied to the ResourcePools as an identifier for this service.
static java.lang.String	CLASS_VERSION Class version string

Fields inherited from class atg.nucleus.GenericService

SERVICE_INFO_KEY

Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging

DEFAULT_LOG_TRACE_STATUS

Fields inherited from interface atg.nucleus.logging.ApplicationLogging

DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS

Constructor Summary

Constructors

Constructor and Description
UpdateService()

Method Summary

Methods

Modifier and Type	Method and Description
AddService	getAddService() If no items are selected for an update, and this component is instructed to add the item when no items are matched, the addItem method will be called on this configured AddService.
java.lang.String	getInputString(java.io.Reader pReader)
MutableRepositoryItem	getSingleUpdatableItem(RepositoryItem[] pItems) This method extracts a single MutableRepositoryItem from the array of RepositoryItems passed to it.
atg.repository.xml.ModifyHandlerResourcePool	getUpdateHandlerPool() Maintain a pool of ContentHandlers that will be used to process an instance document.
boolean	isAddWhenNoMatchedItems() If not items are matched for an update, then this compoent can decide to add the items to the repository.
void	setAddService(AddService addService) Sets the addService.
void	setAddWhenNoMatchedItems(boolean addWhenNoMatchedItems) Sets the addWhenNoMatchedItems.
void	setPropertiesOnContentHandler(atg.repository.xml.UpdateHandler pContentHandler, boolean pEmptyTagIsNull, boolean pMissingTagIsNull, boolean pIsPersistItem, boolean pEmptyTagIsEmptyString, MutableRepositoryItem pItem) This method will set properties on the contentHandler that control how the contentHandler will process a given instance document.
void	setUpdateHandlerPool(atg.repository.xml.ModifyHandlerResourcePool pUpdateHandlerPool) Set the UpdateHandlerPool property.
RepositoryItem	updateItem(org.xml.sax.InputSource pInputSource, boolean pIsValidate, boolean pEmptyTagIsNull, boolean pMissingTagIsNull, boolean pIsPersistItem, boolean pIsEmptyTagIsEmptyString, MutableRepositoryItem pItem) All method expected to be called by the user will eventually call this method to actually perform the work of adding a repository item to the repository.
RepositoryItem	updateItem(java.io.InputStream pXMLInput, boolean pIsValidate, boolean pIsEmptyTagIsNull, boolean pIsMissingTagIsNull, boolean pIsPersistItem, boolean pIsEmptyTagIsEmptyString, java.lang.String[] pMatchProperties) This method will potentially update an item in a repository.
RepositoryItem	updateItem(java.io.InputStream pXMLInput, java.util.Map pMatchValues) This method will potentially update an item in a repository.
RepositoryItem	updateItem(java.io.InputStream pXMLInput, MutableRepositoryItem pItem) The item specified by the pItem parameter will be udpated with the property values found in the pXMLInput parameter.
RepositoryItem	updateItem(java.io.InputStream pXMLInput, java.lang.String[] pMatchProperties) This method will potentially update an item in a repository.
RepositoryItem	updateItem(java.io.Reader pXMLInput, boolean pIsValidate, boolean pIsEmptyTagIsNull, boolean pIsMissingTagIsNull, boolean pIsPersistItem, boolean pIsEmptyTagIsEmptyString, java.lang.String[] pMatchProperties) This method will potentially update an item in a repository.
RepositoryItem	updateItem(java.io.Reader pXMLInput, java.util.Map pMatchValues) This method will potentially update an item in a repository.
RepositoryItem	updateItem(java.io.Reader pXMLInput, MutableRepositoryItem pItem) The item specified by the pItem parameter will be udpated with the property values found in the pXMLInput parameter.
RepositoryItem	updateItem(java.io.Reader pXMLInput, java.lang.String[] pMatchProperties) This method will potentially update an item in a repository.
RepositoryItem	updateItem(java.lang.String pXMLInput, boolean pIsValidate, boolean pIsEmptyTagIsNull, boolean pIsMissingTagIsNull, boolean pIsPersistItem, boolean pIsEmptyTagIsEmptyString, java.util.Map pMatchValues) This method is responsible for obtaining the repository item to update and deciding if no item is selected whether the instance document should result in a new item being added to the repository.
RepositoryItem	updateItem(java.lang.String pXMLInput, boolean pIsValidate, boolean pIsEmptyTagIsNull, boolean pIsMissingTagIsNull, boolean pIsPersistItem, boolean pIsEmptyTagIsEmptyString, java.util.Map pMatchValues, java.lang.String pId) This method is responsible for obtaining the repository item to update and deciding if no item is selected whether the instance document should result in a new item being added to the repository.
RepositoryItem	updateItem(java.lang.String pXMLInput, boolean pIsValidate, boolean pIsEmptyTagIsNull, boolean pIsMissingTagIsNull, boolean pIsPersistItem, boolean pIsEmptyTagIsEmptyString, java.lang.String[] pMatchProperties) This method is responsible for obtaining the repository item to update and deciding if no item is selected whether the instance document should result in a new item being added to the repository.
RepositoryItem	updateItem(java.lang.String pXMLInput, boolean pIsValidate, boolean pIsEmptyTagIsNull, boolean pIsMissingTagIsNull, boolean pIsPersistItem, boolean pIsEmptyTagIsEmptyString, java.lang.String[] pMatchProperties, java.lang.String pId) This method is responsible for obtaining the repository item to update and deciding if no item is selected whether the instance document should result in a new item being added to the repository.
RepositoryItem	updateItem(java.lang.String pXMLInput, java.util.Map pMatchValues) This method will potentially update an item in a repository.
RepositoryItem	updateItem(java.lang.String pXMLInput, MutableRepositoryItem pItem) The item specified by the pItem parameter will be udpated with the property values found in the pXMLInput parameter.
RepositoryItem	updateItem(java.lang.String pXMLInput, java.lang.String[] pMatchProperties) This method will potentially update an item in a repository.

Methods inherited from class atg.repository.xml.ModifyService

clearGsaIdCache, error, fatalError, getCache, getCache, getDateFormat, getGsaIdCache, getRepositoryXMLTools, getSAXParserPool, getSchemaManager, getTransactionManager, isEmptyTagIsEmptyString, isEmptyTagIsNull, isLogWarningOnReadOnly, isMissingTagIsNull, isPersistItem, isUseGsaIdCache, isValidate, prepopulateCache, setDateFormat, setEmptyTagIsEmptyString, setEmptyTagIsNull, setFeaturesForXMLReader, setHandlersForXMLReader, setLogWarningOnReadOnly, setMissingTagIsNull, setPersistItem, setRepositoryXMLTools, setSAXParserPool, setSchemaManager, setTransactionManager, setUseGsaIdCache, setValidate, warning

Methods inherited from class atg.nucleus.GenericService

addLogListener, createAdminServlet, doStartService, doStopService, getAbsoluteName, getAdminServlet, getAdminServletOutputStreamEncoding, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isAdminServletUseServletOutputStream, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, reResolveThis, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setAdminServletOutputStreamEncoding, setAdminServletUseServletOutputStream, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogDebugTrace, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

Class version string

CHECKOUT_TAG

public static final java.lang.String CHECKOUT_TAG

Tag supplied to the ResourcePools as an identifier for this service.

See Also:

Constant Field Values

Constructor Detail

UpdateService

public UpdateService()

Method Detail

isAddWhenNoMatchedItems

public boolean isAddWhenNoMatchedItems()

If not items are matched for an update, then this compoent can decide to add the items to the repository. This behavior is controlled by this property.

Returns:

boolean true if when no items are matched for an update, if the the item should be added to the repository.

setAddWhenNoMatchedItems

public void setAddWhenNoMatchedItems(boolean addWhenNoMatchedItems)

Sets the addWhenNoMatchedItems.

Parameters:

addWhenNoMatchedItems - The addWhenNoMatchedItems to set

getAddService

public AddService getAddService()

If no items are selected for an update, and this component is instructed to add the item when no items are matched, the addItem method will be called on this configured AddService.

Returns:

AddService the service that will be used to add items to the repository when no items are selected for an update.

setAddService

public void setAddService(AddService addService)

Sets the addService.

Parameters:

addService - The addService to set

getUpdateHandlerPool

public atg.repository.xml.ModifyHandlerResourcePool getUpdateHandlerPool()

Maintain a pool of ContentHandlers that will be used to process an instance document. These objects are pooled to increase the amount of time it takes to process an instance document.

Returns:

ResourcePool of UpdateHandler objects that are ContentHandlers for the processing of an instnace document.

setUpdateHandlerPool

public void setUpdateHandlerPool(atg.repository.xml.ModifyHandlerResourcePool pUpdateHandlerPool)

Set the UpdateHandlerPool property.

Parameters:

pUpdateHandlerPool -

updateItem

public RepositoryItem updateItem(java.lang.String pXMLInput,
                        java.lang.String[] pMatchProperties)
                          throws UpdateException,
                                 MatchException,
                                 MaxNumberItemsException

This method will potentially update an item in a repository. An InputSource object will be created and then the #updateItem(InputSource, String, boolean, boolean, boolean, boolean, String[] method will be called.

All parameters passed to the updateItem() method will be obtained from the values specified on this component. For example, whether to validate the incoming instance document will be determined by the isValidate() property of this class.

Parameters:

pXMLInput - the XML instance containing the values to update.

pMatchProperties - properties to match on. Items will be selected out of the repository whose properties (corresponding to those in the matchProperties) have values equal to the item in the pXMLInput

Returns:

RepositoryItem the item that was updated/added

Throws:

UpdateException - if an error occurs

MatchException - if there was a problem finding matching items in the repository

MaxNumberItemsException - if more then one item was selected for update.

updateItem

public RepositoryItem updateItem(java.lang.String pXMLInput,
                        java.util.Map pMatchValues)
                          throws UpdateException,
                                 MatchException,
                                 MaxNumberItemsException

This method will potentially update an item in a repository. An InputSource object will be created and then the #updateItem(InputSource, String, boolean, boolean, boolean, boolean, Map method will be called.

All parameters passed to the updateItem() method will be obtained from the values specified on this component. For example, whether to validate the incoming instance document will be determined by the isValidate() property of this class.

Parameters:

pXMLInput - the XML instance containing the values to update.

pMatchValues - Set of key/value pairs that we should match on. Items will be selected out of the repository whose properties (corresponding to the key in the pMatchValues) have values equal to corresponding the values in the pMatchValues.

Returns:

RepositoryItem the item that was updated/added

Throws:

UpdateException - if an error occurs

MatchException - if there was a problem finding matching items in the repository

MaxNumberItemsException - if more then one item was selected for update.

updateItem

public RepositoryItem updateItem(java.io.InputStream pXMLInput,
                        java.lang.String[] pMatchProperties)
                          throws UpdateException,
                                 MatchException,
                                 MaxNumberItemsException

This method will potentially update an item in a repository. An InputSource object will be created and then the #updateItem(InputSource, String, boolean, boolean, boolean, boolean, String[] method will be called. *

All parameters passed to the updateItem() method will be obtained from the values specified on this component. For example, whether to validate the incoming instance document will be determined by the isValidate() property of this class.

Parameters:

pXMLInput - the XML instance containing the values to update.

pMatchProperties - properties to match on. Items will be selected out of the repository whose properties (corresponding to those in the matchProperties) have values equal to the item in the pXMLInput

Returns:

RepositoryItem the item that was updated/added

Throws:

UpdateException - if an error occurs

MatchException - if there was a problem finding matching items in the repository

MaxNumberItemsException - if more then one item was selected for update.

updateItem

public RepositoryItem updateItem(java.io.InputStream pXMLInput,
                        java.util.Map pMatchValues)
                          throws UpdateException,
                                 MatchException,
                                 MaxNumberItemsException

This method will potentially update an item in a repository. An InputSource object will be created and then the #updateItem(InputSource, String, boolean, boolean, boolean, boolean, String[] method will be called. *

All parameters passed to the updateItem() method will be obtained from the values specified on this component. For example, whether to validate the incoming instance document will be determined by the isValidate() property of this class.

Parameters:

pXMLInput - the XML instance containing the values to update.

pMatchValues - Set of key/value pairs that we should match on. Items will be selected out of the repository whose properties (corresponding to the key in the pMatchValues) have values equal to corresponding the values in the pMatchValues.

Returns:

RepositoryItem the item that was updated/added

Throws:

UpdateException - if an error occurs

MatchException - if there was a problem finding matching items in the repository

MaxNumberItemsException - if more then one item was selected for update.

updateItem

public RepositoryItem updateItem(java.io.Reader pXMLInput,
                        java.lang.String[] pMatchProperties)
                          throws UpdateException,
                                 MatchException,
                                 MaxNumberItemsException

This method will potentially update an item in a repository. An InputSource object will be created and then the #updateItem(InputSource, String, boolean, boolean, boolean, boolean, String[] method will be called. *

All parameters passed to the updateItem() method will be obtained from the values specified on this component. For example, whether to validate the incoming instance document will be determined by the isValidate() property of this class.

Parameters:

pXMLInput - the XML instance containing the values to update.

pMatchProperties - properties to match on. Items will be selected out of the repository whose properties (corresponding to those in the matchProperties) have values equal to the item in the pXMLInput

Returns:

RepositoryItem the item that was updated/added

Throws:

UpdateException - if an error occurs

MatchException - if there was a problem finding matching items in the repository

MaxNumberItemsException - if more then one item was selected for update.

updateItem

public RepositoryItem updateItem(java.io.Reader pXMLInput,
                        java.util.Map pMatchValues)
                          throws UpdateException,
                                 MatchException,
                                 MaxNumberItemsException

This method will potentially update an item in a repository. An InputSource object will be created and then the #updateItem(InputSource, String, boolean, boolean, boolean, boolean, String[] method will be called. *

All parameters passed to the updateItem() method will be obtained from the values specified on this component. For example, whether to validate the incoming instance document will be determined by the isValidate() property of this class.

Parameters:

pXMLInput - the XML instance containing the values to update.

pMatchValues - Set of key/value pairs that we should match on. Items will be selected out of the repository whose properties (corresponding to the key in the pMatchValues) have values equal to corresponding the values in the pMatchValues.

Returns:

RepositoryItem the item that was updated/added

Throws:

UpdateException - if an error occurs

MatchException - if there was a problem finding matching items in the repository

MaxNumberItemsException - if more then one item was selected for update.

updateItem

public RepositoryItem updateItem(java.io.InputStream pXMLInput,
                        boolean pIsValidate,
                        boolean pIsEmptyTagIsNull,
                        boolean pIsMissingTagIsNull,
                        boolean pIsPersistItem,
                        boolean pIsEmptyTagIsEmptyString,
                        java.lang.String[] pMatchProperties)
                          throws UpdateException,
                                 MatchException,
                                 MaxNumberItemsException

This method will potentially update an item in a repository. An InputSource object will be created and then the #updateItem(InputSource, String, boolean, boolean, boolean, boolean, String[] method will be called.

Parameters:

pXMLInput - the XML instance containing the values to update.

pIsValidate - should instance documents be validated against their corresponding Schema. The Schema is obtained by using an EntityResolver. The EntityResolver used is the configured SchemaManager component. There should be an entry in a given instance document for schemaLocation with the value equal to the namespace of the document.

pEmptyTagIsNull - should empty tags be treated as null. For example, if an element appeared in an instance document that looked like <firstName/> this could either result in the firstName property being set to null explicitly on the repository item, or skip setting any value on the property. If this parameter is true, then null is set explicitly, else no property is set.

pMissingTagIsNull - if this property is set to true, then all tags that fail appear in a given instance document will have their corresponding properties set to null on the repository item. For example, if the firstName element had failed to appear in an instance document then if this property was true null would be set for the firstName property.

pIsPersistItem - if this is true, then any item created will also be persisted to the repository by calling the addItem() method.

pIsEmptyTagIsEmptyString - if this is true, then any empty tags will result in setting the empty string assigned to the corresponding property

pMatchProperties - properties to match on. Items will be selected out of the repository whose properties (corresponding to those in the matchProperties) have values equal to the item in the pXMLInput

Returns:

RepositoryItem the item that was updated/added

Throws:

UpdateException - if an error occurs

MatchException - if there was a problem finding matching items in the repository

MaxNumberItemsException - if more then one item was selected for update.

updateItem

public RepositoryItem updateItem(java.io.Reader pXMLInput,
                        boolean pIsValidate,
                        boolean pIsEmptyTagIsNull,
                        boolean pIsMissingTagIsNull,
                        boolean pIsPersistItem,
                        boolean pIsEmptyTagIsEmptyString,
                        java.lang.String[] pMatchProperties)
                          throws UpdateException,
                                 MatchException,
                                 MaxNumberItemsException

This method will potentially update an item in a repository. An InputSource object will be created and then the #updateItem(InputSource, String, boolean, boolean, boolean, boolean, String[] method will be called.

Parameters:

pXMLInput - the XML instance containing the values to update.

pIsValidate - should instance documents be validated against their corresponding Schema. The Schema is obtained by using an EntityResolver. The EntityResolver used is the configured SchemaManager component. There should be an entry in a given instance document for schemaLocation with the value equal to the namespace of the document.

pEmptyTagIsNull - should empty tags be treated as null. For example, if an element appeared in an instance document that looked like <firstName/> this could either result in the firstName property being set to null explicitly on the repository item, or skip setting any value on the property. If this parameter is true, then null is set explicitly, else no property is set.

pMissingTagIsNull - if this property is set to true, then all tags that fail appear in a given instance document will have their corresponding properties set to null on the repository item. For example, if the firstName element had failed to appear in an instance document then if this property was true null would be set for the firstName property.

pIsPersistItem - if this is true, then any item created will also be persisted to the repository by calling the addItem() method.

pIsEmptyTagIsEmptyString - if this is true, then any empty tags will result in setting the empty string assigned to the corresponding property

pMatchProperties - properties to match on. Items will be selected out of the repository whose properties (corresponding to those in the matchProperties) have values equal to the item in the pXMLInput

Returns:

RepositoryItem the item that was updated/added

Throws:

UpdateException - if an error occurs

MatchException - if there was a problem finding matching items in the repository

MaxNumberItemsException - if more then one item was selected for update.

updateItem

public RepositoryItem updateItem(java.lang.String pXMLInput,
                        MutableRepositoryItem pItem)
                          throws UpdateException

The item specified by the pItem parameter will be udpated with the property values found in the pXMLInput parameter.

All values concerning whether to validate the incoming document, to treate empty tags as null etc. will be set to the property values on this component for their respective property.

This method is used when the item to be updated is known before calling a method on this component.

Parameters:

pXMLInput - the instance document containing the values to update

pItem - the item to be updated

Returns:

RepositoryItem the updated repositoyr item

Throws:

UpdateException - if an error occurs

updateItem

public RepositoryItem updateItem(java.io.InputStream pXMLInput,
                        MutableRepositoryItem pItem)
                          throws UpdateException

The item specified by the pItem parameter will be udpated with the property values found in the pXMLInput parameter.

All values concerning whether to validate the incoming document, to treate empty tags as null etc. will be set to the property values on this component for their respective property.

This method is used when the item to be updated is known before calling a method on this component.

Parameters:

pXMLInput - the instance document containing the values to update

pItem - the item to be updated

Returns:

RepositoryItem the updated repositoyr item

Throws:

UpdateException - if an error occurs

updateItem

public RepositoryItem updateItem(java.io.Reader pXMLInput,
                        MutableRepositoryItem pItem)
                          throws UpdateException

The item specified by the pItem parameter will be udpated with the property values found in the pXMLInput parameter.

All values concerning whether to validate the incoming document, to treate empty tags as null etc. will be set to the property values on this component for their respective property.

This method is used when the item to be updated is known before calling a method on this component.

Parameters:

pXMLInput - the instance document containing the values to update

pItem - the item to be updated

Returns:

RepositoryItem the updated repositoyr item

Throws:

UpdateException - if an error occurs

updateItem

public RepositoryItem updateItem(java.lang.String pXMLInput,
                        boolean pIsValidate,
                        boolean pIsEmptyTagIsNull,
                        boolean pIsMissingTagIsNull,
                        boolean pIsPersistItem,
                        boolean pIsEmptyTagIsEmptyString,
                        java.lang.String[] pMatchProperties)
                          throws UpdateException,
                                 MatchException,
                                 MaxNumberItemsException

This method is responsible for obtaining the repository item to update and deciding if no item is selected whether the instance document should result in a new item being added to the repository. The getItemForUpdate() method on this class is used to select the repository item to be updated. If no item is found to match, then this method will check the isAddWhenNoMatchedItems property on this class. If its true, then the item will be added to the repository. Else, a UpdateException will be thrown indicating that no matching items were found.

Parameters:

pXMLInput - the XML instance containing the values to update.

pIsValidate - should instance documents be validated against their corresponding Schema. The Schema is obtained by using an EntityResolver. The EntityResolver used is the configured SchemaManager component. There should be an entry in a given instance document for schemaLocation with the value equal to the namespace of the document.

pEmptyTagIsNull - should empty tags be treated as null. For example, if an element appeared in an instance document that looked like <firstName/> this could either result in the firstName property being set to null explicitly on the repository item, or skip setting any value on the property. If this parameter is true, then null is set explicitly, else no property is set.

pMissingTagIsNull - if this property is set to true, then all tags that fail appear in a given instance document will have their corresponding properties set to null on the repository item. For example, if the firstName element had failed to appear in an instance document then if this property was true null would be set for the firstName property.

pIsPersistItem - if this is true, then any item created will also be persisted to the repository by calling the addItem() method.

pIsEmptyTagIsEmptyString - if this is true, then any empty tags will result in setting the empty string assigned to the corresponding property

pMatchProperties - properties to match on. Items will be selected out of the repository whose properties (corresponding to those in the matchProperties) have values equal to the item in the pXMLInput

Returns:

RepositoryItem the item that was updated/added

Throws:

UpdateException - if an error occurs

MatchException - if there was a problem finding matching items in the repository

MaxNumberItemsException - if more then one item was selected for update.

updateItem

public RepositoryItem updateItem(java.lang.String pXMLInput,
                        boolean pIsValidate,
                        boolean pIsEmptyTagIsNull,
                        boolean pIsMissingTagIsNull,
                        boolean pIsPersistItem,
                        boolean pIsEmptyTagIsEmptyString,
                        java.lang.String[] pMatchProperties,
                        java.lang.String pId)
                          throws UpdateException,
                                 MatchException,
                                 MaxNumberItemsException

This method is responsible for obtaining the repository item to update and deciding if no item is selected whether the instance document should result in a new item being added to the repository. The getItemForUpdate() method on this class is used to select the repository item to be updated. If no item is found to match, then this method will check the isAddWhenNoMatchedItems property on this class. If its true, then the item will be added to the repository. Else, a UpdateException will be thrown indicating that no matching items were found.

Parameters:

pXMLInput - the XML instance containing the values to update.

pIsValidate - should instance documents be validated against their corresponding Schema. The Schema is obtained by using an EntityResolver. The EntityResolver used is the configured SchemaManager component. There should be an entry in a given instance document for schemaLocation with the value equal to the namespace of the document.

pEmptyTagIsNull - should empty tags be treated as null. For example, if an element appeared in an instance document that looked like <firstName/> this could either result in the firstName property being set to null explicitly on the repository item, or skip setting any value on the property. If this parameter is true, then null is set explicitly, else no property is set.

pMissingTagIsNull - if this property is set to true, then all tags that fail appear in a given instance document will have their corresponding properties set to null on the repository item. For example, if the firstName element had failed to appear in an instance document then if this property was true null would be set for the firstName property.

pIsPersistItem - if this is true, then any item created will also be persisted to the repository by calling the addItem() method.

pIsEmptyTagIsEmptyString - if this is true, then any empty tags will result in setting the empty string assigned to the corresponding property

pMatchProperties - properties to match on. Items will be selected out of the repository whose properties (corresponding to those in the matchProperties) have values equal to the item in the pXMLInput

pId - the the string that, if not null, should be used as the id of the "top level" repository item created if no item was found for the update and addWhenNoMatchedItems is true

Returns:

RepositoryItem the item that was updated/added

Throws:

UpdateException - if an error occurs

MatchException - if there was a problem finding matching items in the repository

MaxNumberItemsException - if more then one item was selected for update.

updateItem

public RepositoryItem updateItem(java.lang.String pXMLInput,
                        boolean pIsValidate,
                        boolean pIsEmptyTagIsNull,
                        boolean pIsMissingTagIsNull,
                        boolean pIsPersistItem,
                        boolean pIsEmptyTagIsEmptyString,
                        java.util.Map pMatchValues)
                          throws UpdateException,
                                 MatchException,
                                 MaxNumberItemsException

This method is responsible for obtaining the repository item to update and deciding if no item is selected whether the instance document should result in a new item being added to the repository. The getItemForUpdate() method on this class is used to select the repository item to be updated. If no item is found to match, then this method will check the isAddWhenNoMatchedItems property on this class. If its true, then the item will be added to the repository. Else, a UpdateException will be thrown indicating that no matching items were found.

Parameters:

pXMLInput - the XML instance containing the values to update.

pIsValidate - should instance documents be validated against their corresponding Schema. The Schema is obtained by using an EntityResolver. The EntityResolver used is the configured SchemaManager component. There should be an entry in a given instance document for schemaLocation with the value equal to the namespace of the document.

pEmptyTagIsNull - should empty tags be treated as null. For example, if an element appeared in an instance document that looked like <firstName/> this could either result in the firstName property being set to null explicitly on the repository item, or skip setting any value on the property. If this parameter is true, then null is set explicitly, else no property is set.

pMissingTagIsNull - if this property is set to true, then all tags that fail appear in a given instance document will have their corresponding properties set to null on the repository item. For example, if the firstName element had failed to appear in an instance document then if this property was true null would be set for the firstName property.

pIsPersistItem - if this is true, then any item created will also be persisted to the repository by calling the addItem() method.

pIsEmptyTagIsEmptyString - if this is true, then any empty tags will result in setting the empty string assigned to the corresponding property

pMatchValues - Set of key/value pairs that we should match on. Items will be selected out of the repository whose properties (corresponding to the key in the pMatchValues) have values equal to corresponding the values in the pMatchValues. pXMLInput

Returns:

RepositoryItem the item that was updated/added

Throws:

UpdateException - if an error occurs

MatchException - if there was a problem finding matching items in the repository

MaxNumberItemsException - if more then one item was selected for update.

updateItem

public RepositoryItem updateItem(java.lang.String pXMLInput,
                        boolean pIsValidate,
                        boolean pIsEmptyTagIsNull,
                        boolean pIsMissingTagIsNull,
                        boolean pIsPersistItem,
                        boolean pIsEmptyTagIsEmptyString,
                        java.util.Map pMatchValues,
                        java.lang.String pId)
                          throws UpdateException,
                                 MatchException,
                                 MaxNumberItemsException

This method is responsible for obtaining the repository item to update and deciding if no item is selected whether the instance document should result in a new item being added to the repository. The getItemForUpdate() method on this class is used to select the repository item to be updated. If no item is found to match, then this method will check the isAddWhenNoMatchedItems property on this class. If its true, then the item will be added to the repository. Else, a UpdateException will be thrown indicating that no matching items were found.

Parameters:

pXMLInput - the XML instance containing the values to update.

pIsValidate - should instance documents be validated against their corresponding Schema. The Schema is obtained by using an EntityResolver. The EntityResolver used is the configured SchemaManager component. There should be an entry in a given instance document for schemaLocation with the value equal to the namespace of the document.

pEmptyTagIsNull - should empty tags be treated as null. For example, if an element appeared in an instance document that looked like <firstName/> this could either result in the firstName property being set to null explicitly on the repository item, or skip setting any value on the property. If this parameter is true, then null is set explicitly, else no property is set.

pMissingTagIsNull - if this property is set to true, then all tags that fail appear in a given instance document will have their corresponding properties set to null on the repository item. For example, if the firstName element had failed to appear in an instance document then if this property was true null would be set for the firstName property.

pIsPersistItem - if this is true, then any item created will also be persisted to the repository by calling the addItem() method.

pIsEmptyTagIsEmptyString - if this is true, then any empty tags will result in setting the empty string assigned to the corresponding property

pMatchValues - Set of key/value pairs that we should match on. Items will be selected out of the repository whose properties (corresponding to the key in the pMatchValues) have values equal to corresponding the values in the pMatchValues. pXMLInput

pId - the the string that, if not null, should be used as the id of the "top level" repository item created if no item was found for the update and addWhenNoMatchedItems is true

Returns:

RepositoryItem the item that was updated/added

Throws:

UpdateException - if an error occurs

MatchException - if there was a problem finding matching items in the repository

MaxNumberItemsException - if more then one item was selected for update.

updateItem

public RepositoryItem updateItem(org.xml.sax.InputSource pInputSource,
                        boolean pIsValidate,
                        boolean pEmptyTagIsNull,
                        boolean pMissingTagIsNull,
                        boolean pIsPersistItem,
                        boolean pIsEmptyTagIsEmptyString,
                        MutableRepositoryItem pItem)
                          throws UpdateException

All method expected to be called by the user will eventually call this method to actually perform the work of adding a repository item to the repository.

Parameters:

pInputSource - SAX InputSource Object

pIsValidate - whether instance documents should be validated

pEmptyTagIsNull - whether empty tags are considered null or empty tags mean that no value was supplied so setting a property on the repository item should be skipped.

pMissingTagIsNull - if a tag is missing in the instance document, should setting a value on the repository item be skipped.

Returns:

the RepositoryItem that was created.

Throws:

UpdateException

getSingleUpdatableItem

public MutableRepositoryItem getSingleUpdatableItem(RepositoryItem[] pItems)
                                             throws UpdateException,
                                                    RepositoryException,
                                                    MaxNumberItemsException

This method extracts a single MutableRepositoryItem from the array of RepositoryItems passed to it.

Parameters:

pItems - the array of items that is expected to have a single item that is a MutableRepositoryItem

Returns:

an item that is a MutableRepositoryItem

Throws:

UpdateException - if an error occurred while updating

MaxNumberItemsException - If more then one item appears in the array

RepositoryException - if an error occurs

setPropertiesOnContentHandler

public void setPropertiesOnContentHandler(atg.repository.xml.UpdateHandler pContentHandler,
                                 boolean pEmptyTagIsNull,
                                 boolean pMissingTagIsNull,
                                 boolean pIsPersistItem,
                                 boolean pEmptyTagIsEmptyString,
                                 MutableRepositoryItem pItem)
                                   throws java.io.IOException,
                                          javax.xml.parsers.ParserConfigurationException,
                                          org.xml.sax.SAXException,
                                          RepositoryException

This method will set properties on the contentHandler that control how the contentHandler will process a given instance document. All parameters are set onto the pContentHandler parameter passed to this method. Additionally, the AddService property is set on the contentHandler, which is set to this AddService object.

Parameters:

pContentHandler - the contentHandler that will have its properties set

pEmptyTagIsNull - are empty tags treated as explicit null

pMissingTagIsNull - are missing tags from the instance document treated as explicit null

pEmptyTagIsEmptyString - are empty tags treated as empty String for String properties

Throws:

java.io.IOException

javax.xml.parsers.ParserConfigurationException

org.xml.sax.SAXException

RepositoryException

getInputString

public java.lang.String getInputString(java.io.Reader pReader)
                                throws UpdateException

Throws:

UpdateException