com.google.protobuf

Class ExtensionRegistry

java.lang.Object

com.google.protobuf.ExtensionRegistryLite

com.google.protobuf.ExtensionRegistry

public class ExtensionRegistry
extends ExtensionRegistryLite

A table of known extensions, searchable by name or field number. When parsing a protocol message that might have extensions, you must provide an ExtensionRegistry in which you have registered any extensions that you want to be able to parse. Otherwise, those extensions will just be treated like unknown fields.

For example, if you had the .proto file:

 option java_class = "MyProto";

 message Foo {
   extensions 1000 to max;
 }

 extend Foo {
   optional int32 bar;
 }
 

Then you might write code like:

 ExtensionRegistry registry = ExtensionRegistry.newInstance();
 registry.add(MyProto.bar);
 MyProto.Foo message = MyProto.Foo.parseFrom(input, registry);
 

Background:

You might wonder why this is necessary. Two alternatives might come to mind. First, you might imagine a system where generated extensions are automatically registered when their containing classes are loaded. This is a popular technique, but is bad design; among other things, it creates a situation where behavior can change depending on what classes happen to be loaded. It also introduces a security vulnerability, because an unprivileged class could cause its code to be called unexpectedly from a privileged class by registering itself as an extension of the right type.

Another option you might consider is lazy parsing: do not parse an extension until it is first requested, at which point the caller must provide a type to use. This introduces a different set of problems. First, it would require a mutex lock any time an extension was accessed, which would be slow. Second, corrupt data would not be detected until first access, at which point it would be much harder to deal with it. Third, it could violate the expectation that message objects are immutable, since the type provided could be any arbitrary message class. An unprivileged user could take advantage of this to inject a mutable object into a message belonging to privileged code and create mischief.

Author:

[email protected] Kenton Varda

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ExtensionRegistry.ExtensionInfo A (Descriptor, Message) pair, returned by lookup methods.

Method Summary

Modifier and Type	Method and Description
void	add(Descriptors.FieldDescriptor type) Add a non-message-type extension to the registry by descriptor.
void	add(Descriptors.FieldDescriptor type, Message defaultInstance) Add a message-type extension to the registry by descriptor.
void	add(Extension<?,?> extension) Add an extension from a generated file to the registry.
void	add(GeneratedMessage.GeneratedExtension<?,?> extension) Add an extension from a generated file to the registry.
ExtensionRegistry.ExtensionInfo	findExtensionByName(String fullName) Deprecated.
ExtensionRegistry.ExtensionInfo	findExtensionByNumber(Descriptors.Descriptor containingType, int fieldNumber) Deprecated.
ExtensionRegistry.ExtensionInfo	findImmutableExtensionByName(String fullName) Find an extension for immutable APIs by fully-qualified field name, in the proto namespace.
ExtensionRegistry.ExtensionInfo	findImmutableExtensionByNumber(Descriptors.Descriptor containingType, int fieldNumber) Find an extension by containing type and field number for immutable APIs.
ExtensionRegistry.ExtensionInfo	findMutableExtensionByName(String fullName) Find an extension for mutable APIs by fully-qualified field name, in the proto namespace.
ExtensionRegistry.ExtensionInfo	findMutableExtensionByNumber(Descriptors.Descriptor containingType, int fieldNumber) Find an extension by containing type and field number for mutable APIs.
Set<ExtensionRegistry.ExtensionInfo>	getAllImmutableExtensionsByExtendedType(String fullName) Find all extensions for immutable APIs by fully-qualified name of extended class.
Set<ExtensionRegistry.ExtensionInfo>	getAllMutableExtensionsByExtendedType(String fullName) Find all extensions for mutable APIs by fully-qualified name of extended class.
static ExtensionRegistry	getEmptyRegistry() Get the unmodifiable singleton empty instance.
ExtensionRegistry	getUnmodifiable() Returns an unmodifiable view of the registry.
static ExtensionRegistry	newInstance() Construct a new, empty instance.

Methods inherited from class com.google.protobuf.ExtensionRegistryLite

add, add, findLiteExtensionByNumber, isEagerlyParseMessageSets, setEagerlyParseMessageSets

Methods inherited from class java.lang.Object

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

Method Detail

newInstance

public static ExtensionRegistry newInstance()

Construct a new, empty instance.

getEmptyRegistry

public static ExtensionRegistry getEmptyRegistry()

Get the unmodifiable singleton empty instance.

getUnmodifiable

public ExtensionRegistry getUnmodifiable()

Returns an unmodifiable view of the registry.

Overrides:

getUnmodifiable in class ExtensionRegistryLite

findExtensionByName

@Deprecated
public ExtensionRegistry.ExtensionInfo findExtensionByName(String fullName)

Deprecated.

Deprecated. Use findImmutableExtensionByName(String) instead.

findImmutableExtensionByName

public ExtensionRegistry.ExtensionInfo findImmutableExtensionByName(String fullName)

Find an extension for immutable APIs by fully-qualified field name, in the proto namespace. i.e. result.descriptor.fullName() will match fullName if a match is found.

Returns:

Information about the extension if found, or null otherwise.

findMutableExtensionByName

public ExtensionRegistry.ExtensionInfo findMutableExtensionByName(String fullName)

Find an extension for mutable APIs by fully-qualified field name, in the proto namespace. i.e. result.descriptor.fullName() will match fullName if a match is found.

Returns:

Information about the extension if found, or null otherwise.

findExtensionByNumber

@Deprecated
public ExtensionRegistry.ExtensionInfo findExtensionByNumber(Descriptors.Descriptor containingType,
                                                                         int fieldNumber)

Deprecated.

Deprecated. Use findImmutableExtensionByNumber( Descriptors.Descriptor, int)

findImmutableExtensionByNumber

public ExtensionRegistry.ExtensionInfo findImmutableExtensionByNumber(Descriptors.Descriptor containingType,
                                                                      int fieldNumber)

Find an extension by containing type and field number for immutable APIs.

Returns:

Information about the extension if found, or null otherwise.

findMutableExtensionByNumber

public ExtensionRegistry.ExtensionInfo findMutableExtensionByNumber(Descriptors.Descriptor containingType,
                                                                    int fieldNumber)

Find an extension by containing type and field number for mutable APIs.

Returns:

Information about the extension if found, or null otherwise.

getAllMutableExtensionsByExtendedType

public Set<ExtensionRegistry.ExtensionInfo> getAllMutableExtensionsByExtendedType(String fullName)

Find all extensions for mutable APIs by fully-qualified name of extended class. Note that this method is more computationally expensive than getting a single extension by name or number.

Returns:

Information about the extensions found, or null if there are none.

getAllImmutableExtensionsByExtendedType

public Set<ExtensionRegistry.ExtensionInfo> getAllImmutableExtensionsByExtendedType(String fullName)

Find all extensions for immutable APIs by fully-qualified name of extended class. Note that this method is more computationally expensive than getting a single extension by name or number.

Returns:

Information about the extensions found, or null if there are none.

add

public void add(Extension<?,?> extension)

Add an extension from a generated file to the registry.

add

public void add(GeneratedMessage.GeneratedExtension<?,?> extension)

Add an extension from a generated file to the registry.

add

public void add(Descriptors.FieldDescriptor type)

Add a non-message-type extension to the registry by descriptor.

add

public void add(Descriptors.FieldDescriptor type,
                Message defaultInstance)

Add a message-type extension to the registry by descriptor.