microsoft.exchange.webservices.data.property.complex.ComplexPropertyCollection Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of de-bwl-lgl-ews-java-api Show documentation
Show all versions of de-bwl-lgl-ews-java-api Show documentation
Exchange Web Services (EWS) Java API
The newest version!
/*
* The MIT License
* Copyright (c) 2012 Microsoft Corporation
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
package microsoft.exchange.webservices.data.property.complex;
import microsoft.exchange.webservices.data.attribute.EditorBrowsable;
import microsoft.exchange.webservices.data.core.EwsServiceXmlReader;
import microsoft.exchange.webservices.data.core.EwsServiceXmlWriter;
import microsoft.exchange.webservices.data.core.EwsUtilities;
import microsoft.exchange.webservices.data.core.ICustomXmlUpdateSerializer;
import microsoft.exchange.webservices.data.core.service.ServiceObject;
import microsoft.exchange.webservices.data.core.enumeration.attribute.EditorBrowsableState;
import microsoft.exchange.webservices.data.core.enumeration.misc.XmlNamespace;
import microsoft.exchange.webservices.data.core.exception.service.local.ServiceLocalException;
import microsoft.exchange.webservices.data.property.definition.PropertyDefinition;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
/**
* Represents a collection of property that can be sent to and retrieved from
* EWS.
*
* @param ComplexProperty type.
*/
@EditorBrowsable(state = EditorBrowsableState.Never)
public abstract class ComplexPropertyCollection
extends ComplexProperty implements ICustomXmlUpdateSerializer,
Iterable, IComplexPropertyChangedDelegate {
/**
* The item.
*/
private final List items = new ArrayList();
/**
* The added item.
*/
private final List addedItems =
new ArrayList();
/**
* The modified item.
*/
private final List modifiedItems =
new ArrayList();
/**
* The removed item.
*/
private final List removedItems =
new ArrayList();
/**
* Creates the complex property.
*
* @param xmlElementName Name of the XML element.
* @return Complex property instance.
*/
protected abstract TComplexProperty createComplexProperty(
String xmlElementName);
/**
* Gets the name of the collection item XML element.
*
* @param complexProperty The complex property.
* @return XML element name.
*/
protected abstract String getCollectionItemXmlElementName(
TComplexProperty complexProperty);
/**
* Initializes a new instance of. ComplexPropertyCollection
*/
protected ComplexPropertyCollection() {
super();
}
/**
* Item changed.
*
* @param property The complex property.
*/
protected void itemChanged(final TComplexProperty property) {
EwsUtilities.ewsAssert(
property != null, "ComplexPropertyCollection.ItemChanged",
"The complexProperty argument must be not null"
);
if (!this.addedItems.contains(property)) {
if (!this.modifiedItems.contains(property)) {
this.modifiedItems.add(property);
this.changed();
}
}
}
/**
* Loads from XML.
*
* @param reader The reader.
* @param localElementName Name of the local element.
*/
@Override public void loadFromXml(EwsServiceXmlReader reader, String localElementName) throws Exception {
this.loadFromXml(
reader,
XmlNamespace.Types,
localElementName);
}
/**
* Loads from XML.
*
* @param reader The reader.
* @param xmlNamespace The XML namespace.
* @param localElementName Name of the local element.
*/
@Override public void loadFromXml(EwsServiceXmlReader reader, XmlNamespace xmlNamespace,
String localElementName) throws Exception {
reader.ensureCurrentNodeIsStartElement(xmlNamespace,
localElementName);
if (!reader.isEmptyElement()) {
do {
reader.read();
if (reader.isStartElement()) {
TComplexProperty complexProperty = this
.createComplexProperty(reader.getLocalName());
if (complexProperty != null) {
complexProperty.loadFromXml(reader, reader
.getLocalName());
this.internalAdd(complexProperty, true);
} else {
reader.skipCurrentElement();
}
}
} while (!reader.isEndElement(xmlNamespace, localElementName));
} else {
reader.read();
}
}
/**
* Loads from XML to update itself.
*
* @param reader The reader.
* @param xmlNamespace The XML namespace.
* @param xmlElementName Name of the XML element.
*/
public void updateFromXml(
EwsServiceXmlReader reader,
XmlNamespace xmlNamespace,
String xmlElementName) throws Exception {
reader.ensureCurrentNodeIsStartElement(xmlNamespace, xmlElementName);
if (!reader.isEmptyElement()) {
int index = 0;
do {
reader.read();
if (reader.isStartElement()) {
TComplexProperty complexProperty = this.createComplexProperty(reader.getLocalName());
TComplexProperty actualComplexProperty = this.getPropertyAtIndex(index++);
if (complexProperty == null || !complexProperty.equals(actualComplexProperty)) {
throw new ServiceLocalException("Property type incompatible when updating collection.");
}
actualComplexProperty.updateFromXml(reader, xmlNamespace, reader.getLocalName());
}
}
while (!reader.isEndElement(xmlNamespace, xmlElementName));
}
}
/**
* Writes to XML.
*
* @param writer The writer.
* @param xmlNamespace The XML namespace.
* @param xmlElementName Name of the XML element.
*/
@Override public void writeToXml(EwsServiceXmlWriter writer, XmlNamespace xmlNamespace,
String xmlElementName) throws Exception {
if (this.shouldWriteToXml()) {
super.writeToXml(
writer,
xmlNamespace,
xmlElementName);
}
}
/**
* Determine whether we should write collection to XML or not.
*
* @return True if collection contains at least one element.
*/
public boolean shouldWriteToXml() {
//Only write collection if it has at least one element.
return this.getCount() > 0;
}
/**
* Writes elements to XML.
*
* @param writer The writer.
* @throws Exception the exception
*/
@Override
public void writeElementsToXml(EwsServiceXmlWriter writer)
throws Exception {
for (TComplexProperty complexProperty : this) {
complexProperty.writeToXml(writer, this
.getCollectionItemXmlElementName(complexProperty));
}
}
/**
* Clears the change log.
*/
@Override public void clearChangeLog() {
this.removedItems.clear();
this.addedItems.clear();
this.modifiedItems.clear();
}
/**
* Removes from change log.
*
* @param complexProperty The complex property.
*/
protected void removeFromChangeLog(TComplexProperty complexProperty) {
this.removedItems.remove(complexProperty);
this.modifiedItems.remove(complexProperty);
this.addedItems.remove(complexProperty);
}
/**
* Gets the item.
*
* @return The item.
*/
public List getItems() {
return this.items;
}
/**
* Gets the added item.
*
* @return The added item.
*/
protected List getAddedItems() {
return this.addedItems;
}
/**
* Gets the modified item.
*
* @return The modified item.
*/
protected List getModifiedItems() {
return this.modifiedItems;
}
/**
* Gets the removed item.
*
* @return The removed item.
*/
protected List getRemovedItems() {
return this.removedItems;
}
/**
* Add complex property.
*
* @param complexProperty The complex property.
*/
protected void internalAdd(TComplexProperty complexProperty) {
this.internalAdd(complexProperty, false);
}
/**
* Add complex property.
*
* @param complexProperty The complex property.
* @param loading If true, collection is being loaded.
*/
private void internalAdd(TComplexProperty complexProperty,
boolean loading) {
EwsUtilities.ewsAssert(complexProperty != null, "ComplexPropertyCollection.InternalAdd",
"complexProperty is null");
if (!this.items.contains(complexProperty)) {
this.items.add(complexProperty);
if (!loading) {
this.removedItems.remove(complexProperty);
this.addedItems.add(complexProperty);
}
complexProperty.addOnChangeEvent(this);
this.changed();
}
}
/**
* Complex property changed.
*
* @param complexProperty accepts ComplexProperty
*/
@Override
public void complexPropertyChanged(final TComplexProperty complexProperty) {
this.itemChanged(complexProperty);
}
/**
* Clear collection.
*/
protected void internalClear() {
while (this.getCount() > 0) {
this.internalRemoveAt(0);
}
}
/**
* Remote entry at index.
*
* @param index The index.
*/
protected void internalRemoveAt(int index) {
EwsUtilities.ewsAssert(index >= 0 && index < this.getCount(),
"ComplexPropertyCollection.InternalRemoveAt", "index is out of range.");
this.internalRemove(this.items.get(index));
}
/**
* Remove specified complex property.
*
* @param complexProperty The complex property.
* @return True if the complex property was successfully removed from the
* collection, false otherwise.
*/
protected boolean internalRemove(TComplexProperty complexProperty) {
EwsUtilities.ewsAssert(complexProperty != null, "ComplexPropertyCollection.InternalRemove",
"complexProperty is null");
if (this.items.remove(complexProperty)) {
complexProperty.removeChangeEvent(this);
if (!this.addedItems.contains(complexProperty)) {
this.removedItems.add(complexProperty);
} else {
this.addedItems.remove(complexProperty);
}
this.modifiedItems.remove(complexProperty);
this.changed();
return true;
} else {
return false;
}
}
/**
* Determines whether a specific property is in the collection.
*
* @param complexProperty The property to locate in the collection.
* @return True if the property was found in the collection, false
* otherwise.
*/
public boolean contains(TComplexProperty complexProperty) {
return this.items.contains(complexProperty);
}
/**
* Searches for a specific property and return its zero-based index within
* the collection.
*
* @param complexProperty The property to locate in the collection.
* @return The zero-based index of the property within the collection.
*/
public int indexOf(TComplexProperty complexProperty) {
return this.items.indexOf(complexProperty);
}
/**
* Gets the total number of property in the collection.
*
* @return the count
*/
public int getCount() {
return this.items.size();
}
/**
* Gets the property at the specified index.
*
* @param index the index
* @return index The property at the specified index.
* @throws IllegalArgumentException thrown if if index is out of range.
*/
public TComplexProperty getPropertyAtIndex(int index)
throws IllegalArgumentException {
if (index < 0 || index >= this.getCount()) {
throw new IllegalArgumentException(
String.format("index %d is out of range [0..%d[.", index, this.getCount())
);
}
return this.items.get(index);
}
/**
* Gets an enumerator that iterates through the elements of the collection.
*
* @return An Iterator for the collection.
*/
@Override
public Iterator iterator() {
return this.items.iterator();
}
/**
* Write set update to xml.
*
* @param writer accepts EwsServiceXmlWriter
* @param ewsObject accepts ServiceObject
* @param propertyDefinition accepts PropertyDefinition
* @return true
* @throws Exception the exception
*/
@Override
public boolean writeSetUpdateToXml(EwsServiceXmlWriter writer,
ServiceObject ewsObject, PropertyDefinition propertyDefinition)
throws Exception {
// If the collection is empty, delete the property.
if (this.getCount() == 0) {
writer.writeStartElement(XmlNamespace.Types, ewsObject
.getDeleteFieldXmlElementName());
propertyDefinition.writeToXml(writer);
writer.writeEndElement();
return true;
}
// Otherwise, use the default XML serializer.
else {
return false;
}
}
/**
* Writes the deletion update to XML.
*
* @param writer The writer.
* @param ewsObject The ews object.
* @return True if property generated serialization.
* @throws Exception the exception
*/
@Override
public boolean writeDeleteUpdateToXml(EwsServiceXmlWriter writer,
ServiceObject ewsObject) throws Exception {
// Use the default XML serializer.
return false;
}
}