Understanding an Enum Class Declaration

[KevinSimonson]

I'm trying to understand how the open source Limewire project's code
works. I'm
taking a look at the source code for enumeration type
<SearchCategory>. It be-
gins like this:

package org.limewire.core.api.search;

import java.util.EnumMap;

import org.limewire.core.api.Category;

/**
* All categories that can be searched.
*/
public enum SearchCategory {
ALL(null, 0),
AUDIO(Category.AUDIO, 1),
VIDEO(Category.VIDEO, 2),
IMAGE(Category.IMAGE, 3),
DOCUMENT(Category.DOCUMENT, 4),
PROGRAM(Category.PROGRAM, 5),
OTHER(Category.OTHER, 6),
TORRENT(Category.TORRENT, 7);

private static final EnumMap<Category, SearchCategory> perCategory
= new EnumMap<Category, SearchCategory>(Category.class);

static {
for(SearchCategory searchCategory : values()) {
if(searchCategory.category != null) {
perCategory.put(searchCategory.category,
searchCategory);
}
}
}

private final Category category;
private final int id;

private SearchCategory(Category category, int id) {
this.id = id;
this.category = category;
}

/**
* Returns the SearchCategory associated with the given Category.
* This will never return {@link SearchCategory#ALL} because
Categories
* are specific to types.
*/
public static SearchCategory forCategory(Category category) {
return perCategory.get(category);
}

It goes on to add more methods. I have no idea what is going on
here. Does
anybody know where I can go to read about Java <enum> types so that I
can under-
stand what this code means? I understand enumeration types from Ada
well
enough, but what's throwing me for a loop is the first parameter in
the paren-
theses after each <enum> constant. For example, take the line that
says,
"VIDEO(Category.VIDEO, 2),". What does <Category.VIDEO> do here?

Also, what's the deal with the class fields <EnumMap>, <category>, and
<id>? In
Ada, if you declare a variable to be of an enumeration type it just
takes one of
a list of values. I had understood that if a variable <sc> was
declared to be
of type <SearchCategory>, then <sc> could be either <ALL>, <AUDIO>,
<VIDEO>, or
any of the other listed values. Can I also get the value <category>
by refer-
ring to <cs.category>?

Finally, after the declaration of <EnumMap>, what's the section
enclosed by
<static {> and <}> all about?

If anybody could explain to me what's going on in this code, or point
me to a
place where this is all documented, I'd really appreciate it.

Kevin Simonson

 

[markspace]

private SearchCategory(Category category, int id) {
this.id = id;
this.category = category;

"VIDEO(Category.VIDEO, 2),". What does<Category.VIDEO> do here?

Gets stored in the instance field "category". This is initialized in
the constructor I quoted above.

Also, what's the deal with the class fields<EnumMap>,<category>, and
<id>? In

catagory and id are instance fields, not class fields.

EnumMap is a type (note the upper case). It is a class field, and its

Finally, after the declaration of<EnumMap>, what's the section
enclosed by
<static {> and<}> all about?

Static initialization block.

If anybody could explain to me what's going on in this code, or point
me to a
place where this is all documented, I'd really appreciate it.

You've omitted enough where it's kinda hard to say what is going on
overall, but most of this is just class declarations. Take a look and
let us know what else still doesn't make sense. Your code isn't much
more complicated than the second example in the official tutorial:

<http://download.oracle.com/javase/tutorial/java/javaOO/enum.html>

 

[Thufir Hawat]

public enum SearchCategory {
ALL(null, 0),
AUDIO(Category.AUDIO, 1),
VIDEO(Category.VIDEO, 2),
IMAGE(Category.IMAGE, 3),
DOCUMENT(Category.DOCUMENT, 4),
PROGRAM(Category.PROGRAM, 5),
OTHER(Category.OTHER, 6),
TORRENT(Category.TORRENT, 7); [...]
private SearchCategory(Category category, int id) {
this.id = id;
this.category = category;
}

GIYF:

http://download.oracle.com/javase/tutorial/java/javaOO/enum.html

The constructor takes the a Category and int based upon which
SearchCategory.Foo was instantiated. SearchCategory.All will, for
example, obviously, pass null and 0 to the constructor.



-Thufir

 

[KevinSimonson]

Okay, I read the API section at "http://download.oracle.com/javase/6/
docs/api/java/util/EnumMap.html", and I think I understand it. But at
the very top of that page it says "java.util / Class EnumMap<K extends
Enum<K>,V>". What exactly does the "<K extends Enum<K>,V>" part
mean? I think it means that class <EnumMap> has two subtypes it's
based on, <K> and <V>, right? But what does the "Enum<K>" part mean?
Any pointers on this would be greatly appreciated.

Kevin Simonson

 

[Lew]

Okay, I read the API section at "http://download.oracle.com/javase/6/
docs/api/java/util/EnumMap.html", and I think I understand it.  But at
the very top of that page it says "java.util / Class EnumMap<K extends
Enum<K>,V>".  What exactly does the "<K extends Enum<K>,V>" part
mean?  I think it means that class <EnumMap> has two subtypes it's
based on, <K> and <V>, right?  But what does the "Enum<K>" part mean?
Any pointers on this would be greatly appreciated.

Read up on generics.

The type parameters 'K' and 'V' represent the key and value types,
respectively, managed by any particular Map instance.

The "extends Enum<K>" part is an assertion that K is an enum type.

The whole declaration asserts that the Map deals with a key type 'K',
to be determined later that is an enum type, and a value type 'V', to
be determined later, that is some subtype of 'Object'.

Some of your questions, like what is a static initialization block,
relate to the basics of the Java language. Others have pointed you to
the tutorials. Read them.

 

[markspace]

Okay, I read the API section at "http://download.oracle.com/javase/6/
docs/api/java/util/EnumMap.html", and I think I understand it. But at
the very top of that page it says "java.util / Class EnumMap<K extends
Enum<K>,V>". What exactly does the"<K extends Enum<K>,V>" part

In this case, it means "K has to be an Enum, and V can be any type." In
other words, K has to extend Enum<K>, which would make K a type of enum.
This syntax parametrizes the type of EnumMap, which means that the
EnumMap will do type checking for you so you don't accidentally put the
wrong type of thing in there.

Note that we have to say Enum<K> instead of Enum because Enum itself has
an <X> parameter type:

mean? I think it means that class<EnumMap> has two subtypes it's
based on,<K> and<V>, right? But what does the "Enum<K>" part mean?
Any pointers on this would be greatly appreciated.

Yes, EnumMap has two parameter types, K and V, which mean Key and Value.
It's the same as all other maps. It maps K -> V, so you need to give
it those two types.

Parameter types come under the subject of generics:

<http://java.sun.com/j2se/1.5/pdf/generics-tutorial.pdf>

 

[Roedy Green]

Does
anybody know where I can go to read about Java <enum> type

for an easy informal introduction, see
http://mindprod.com/jgloss/enum.html

It also shows you the code they generate.