com.github.protobufel.el.package-info Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of protobufel-el Show documentation
ProtoBuf integration with EL 3.0
The newest version!
//
// Copyright © 2014, David Tesler (https://github.com/protobufel)
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
// * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
// * Redistributions in binary form must reproduce the above copyright
// notice, this list of conditions and the following disclaimer in the
// documentation and/or other materials provided with the distribution.
// * Neither the name of the  nor the
// names of its contributors may be used to endorse or promote products
// derived from this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
// DISCLAIMED. IN NO EVENT SHALL  BE LIABLE FOR ANY
// DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
// ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//

/**
 * Enables the ProtoBuf Messages and Builders in JSR-341 EL 3.0 language.
 * 
 * Use ProtoELProcessorEx in place of the original ELProcessor for processing both regular objects
 * and ProtoBuf Messages and Builders.
 * 
The following rules apply to any ProtoBuf {@link Message} and {@link Builder}: 
 * 

 * all non-overloaded and distinct overloaded public methods are available as-is
 * 
overloaded methods with the same number of arguments should be avoided, as the common EL rule
 * 
the fields are treated similarly to EL map properties, by name or FieldDescriptor as the key
 * 
the repeated fields, like EL lists, can be accessed by index
 * 
in addition, Builder's repeated fields have all the additional methods of
 * 
{@link ProtoLists.IRepeatedFieldMessageBuilder} - for the Message type repeated field:
 * 
 * add() - adds and returns the empty field Builder 
 * 
add(value) - adds the MessageOrBuilder value and returns the builder
 * 
add(index, value) - adds the MessageOrBuilder value at index and returns the builder
 * 
addAll(Collection values) - adds all MessageOrBuilder values and returns the builder 
 * 
set(index, value) - sets the MessageOrBuilder value at index and returns the builder
 * 
remove(index) - removes the item at index and returns the builder 
 * 
clear() - clears the repeated field and returns the builder
 * 
getParent() - returns this builder's parent, if any 
 * 
newInstance() - returns a new empty standalone Builder for the field's MessageType
 * 
size() - returns the size of the field
 * 
get(index) - returns a field Builder at index
 * 
getChangedIndex() - returns the last changed item's index
 * 
getChanged(index) - returns the field Builder at index if it changed recently, or null otherwise 
 * 
getLast() - returns the last field Builder
 * 
getList() - returns the entire field's Message list
 * 
getFieldDescriptor() - returns the field's FieldDescriptor
 * 
getType() - returns JavaType.Message
 * 
getBuilders() - returns the entire field's Builder list , for the Builder only
 * 
getMessage(index) - returns the Message at index
 * 
 * 
{@link ProtoLists.IRepeatedFieldValueBuilder} - for any other repeated field
 * 
 * add() - adds a default value and returns it
 * 
add(value) - adds the value and returns the builder
 * 
add(index, value) - adds the value at index and returns the builder
 * 
addAll(Collection values) - adds all values and returns the builder 
 * 
set(index, value) - sets the value at index and returns the builder
 * 
remove(index) - removes the item at index and returns the builder 
 * 
clear() - clears the repeated field and returns the builder
 * 
getParent() - returns this builder's parent, if any 
 * 
newInstance() - returns a new default value of the field type
 * 
size() - returns the size of the field
 * 
get(index) - returns the item at index
 * 
getChangedIndex() - returns the last changed item's index
 * 
getChanged(index) - returns the item at index if it changed recently, or null otherwise 
 * 
getLast() - returns the last item
 * 
getList() - returns the entire field's list of items
 * 
getFieldDescriptor() - returns the field's FieldDescriptor
 * 
getType() - returns the JavaType of the field
 * 
 * 
 * Examples of usage in EL expressions: 
 * 

 * {@code galaxy.name}
 * 
{@code galaxy['name']}
 * 
{@code galaxyBuilder.name = 'Silky Way'}
 * 
{@code galaxyBuilder['name'] = 'E Bay'}
 * 
{@code galaxy.star} - returns the list of Star(-s) 
 * 
{@code galaxy.star[1].name} 
 * 
{@code galaxyBuilder.star} - returns the repeated field Star's special wrapper
 * 
{@code galaxyBuilder.star[0].name}
 * 
{@code galaxyBuilder.star.add()} - returns the new empty star added to the Star field
 * 
{@code sun=galaxyBuilder.star.newInstance(); sun.name='Sun'; galaxyBuilder.star.add(1, sun)
 * .size()}
 * 
{@code galaxyBuilder.star.remove(1).getLast()}
 * 
{@code galaxyBuilder.star.remove(1).toParent().color = 'RED'} - galaxy color set to RED
 * 
{@code galaxyBuilder.star.getBuilders()}
 * 
{@code galaxyBuilder.star.getList()} - returns list of {@code Star}s
 * 
{@code galaxyBuilder.keyword[0] == 'my keyword'} 
 * 
 *
 * @see Examples.java
 * @see galaxy.proto sample
 * @see JSR-000341
 *      Expression Language 3.0
 * @see Protocol Buffers
 *
 * @author [email protected] David Tesler
 */
package com.github.protobufel.el;