001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.util.parse.metapattern;
018
019import java.util.regex.Matcher;
020
021/**
022 * A Group is a piece of a regular expression (referenced by some Java field or local variable) that
023 * forms a "capturing group" within the larger regular expression. A Group is bound to a regular
024 * expression MetaPattern when a matcher is retrieved for the pattern by calling one of the
025 * matcher() methods. Once bound, a Group cannot be rebound.
026 * 
027 * @author Jonathan Locke
028 */
029public class Group extends MetaPattern
030{
031        private static final long serialVersionUID = 1L;
032
033        /** The capturing group that this Group is bound to. */
034        private int group = -1;
035
036        /**
037         * Constructor.
038         * 
039         * @param pattern
040         *            MetaPattern to capture
041         */
042        public Group(final MetaPattern pattern)
043        {
044                super(pattern);
045        }
046
047        /**
048         * Threadsafe method to retrieve contents of this captured group.
049         * 
050         * @param matcher
051         *            The matcher from which to retrieve this Group's group
052         * @return The captured characters
053         */
054        public final String get(final Matcher matcher)
055        {
056                if (group == -1)
057                {
058                        throw new GroupNotBoundException();
059                }
060
061                return matcher.group(group);
062        }
063
064        /**
065         * @see java.lang.Object#toString()
066         */
067        @Override
068        public String toString()
069        {
070                return "(" + super.toString() + ")";
071        }
072
073        /**
074         * Binds this capture expression if not already bound.
075         * 
076         * @param bindTo
077         *            The group to bind to
078         * @throws GroupAlreadyBoundException
079         *             Thrown if this Group is already bound
080         */
081        final void bind(final int bindTo)
082        {
083                if (group == -1)
084                {
085                        group = bindTo;
086                }
087                else
088                {
089                        throw new GroupAlreadyBoundException();
090                }
091        }
092}