THRIFT-4069: perl library cleanup - namespaces, versioning, exception…

… fixes

Client: perl

This closes #1220

compiler/cpp/src/thrift/generate/t_perl_generator.cc

@@ -255,10 +255,12 @@ void t_perl_generator::init_generator() {
 string t_perl_generator::perl_includes() {
   string inc;
 
-  inc = "require 5.6.0;\n";
+  inc  = "use 5.10.0;\n";
   inc += "use strict;\n";
   inc += "use warnings;\n";
-  inc += "use Thrift;\n\n";
+  inc += "use Thrift::Exception;\n";
+  inc += "use Thrift::MessageType;\n";
+  inc += "use Thrift::Type;\n\n";
 
   return inc;
 }
@@ -546,7 +548,7 @@ void t_perl_generator::generate_perl_struct_reader(ofstream& out, t_struct* tstr
   indent(out) << "$xfer += $input->readFieldBegin(\\$fname, \\$ftype, \\$fid);" << endl;
 
   // Check for field STOP marker and break
-  indent(out) << "if ($ftype == TType::STOP) {" << endl;
+  indent(out) << "if ($ftype == Thrift::TType::STOP) {" << endl;
   indent_up();
   indent(out) << "last;" << endl;
   indent_down();
@@ -749,11 +751,11 @@ void t_perl_generator::generate_service_processor(t_service* tservice) {
              << "if (!$self->can($methodname)) {" << endl;
   indent_up();
 
-  f_service_ << indent() << "$input->skip(TType::STRUCT);" << endl << indent()
+  f_service_ << indent() << "$input->skip(Thrift::TType::STRUCT);" << endl << indent()
              << "$input->readMessageEnd();" << endl << indent()
-             << "my $x = new TApplicationException('Function '.$fname.' not implemented.', "
-                "TApplicationException::UNKNOWN_METHOD);" << endl << indent()
-             << "$output->writeMessageBegin($fname, TMessageType::EXCEPTION, $rseqid);" << endl
+             << "my $x = new Thrift::TApplicationException('Function '.$fname.' not implemented.', "
+                "Thrift::TApplicationException::UNKNOWN_METHOD);" << endl << indent()
+             << "$output->writeMessageBegin($fname, Thrift::TMessageType::EXCEPTION, $rseqid);" << endl
              << indent() << "$x->write($output);" << endl << indent()
              << "$output->writeMessageEnd();" << endl << indent()
              << "$output->getTransport()->flush();" << endl << indent() << "return;" << endl;
@@ -851,8 +853,8 @@ void t_perl_generator::generate_process_function(t_service* tservice, t_function
     f_service_ << indent() << "if ($@) {" << endl;
     indent_up();
     f_service_ << indent() << "$@ =~ s/^\\s+|\\s+$//g;" << endl
-               << indent() << "my $err = new TApplicationException(\"Unexpected Exception: \" . $@, TApplicationException::INTERNAL_ERROR);" << endl
-               << indent() << "$output->writeMessageBegin('" << tfunction->get_name() << "', TMessageType::EXCEPTION, $seqid);" << endl
+               << indent() << "my $err = new Thrift::TApplicationException(\"Unexpected Exception: \" . $@, Thrift::TApplicationException::INTERNAL_ERROR);" << endl
+               << indent() << "$output->writeMessageBegin('" << tfunction->get_name() << "', Thrift::TMessageType::EXCEPTION, $seqid);" << endl
                << indent() << "$err->write($output);" << endl
                << indent() << "$output->writeMessageEnd();" << endl
                << indent() << "$output->getTransport()->flush();" << endl
@@ -871,7 +873,7 @@ void t_perl_generator::generate_process_function(t_service* tservice, t_function
   }
 
   // Serialize the reply
-  f_service_ << indent() << "$output->writeMessageBegin('" << tfunction->get_name() << "', TMessageType::REPLY, $seqid);" << endl
+  f_service_ << indent() << "$output->writeMessageBegin('" << tfunction->get_name() << "', Thrift::TMessageType::REPLY, $seqid);" << endl
              << indent() << "$result->write($output);" << endl
              << indent() << "$output->writeMessageEnd();" << endl
              << indent() << "$output->getTransport()->flush();" << endl;
@@ -1096,7 +1098,7 @@ void t_perl_generator::generate_service_client(t_service* tservice) {
 
     // Serialize the request header
     f_service_ << indent() << "$self->{output}->writeMessageBegin('" << (*f_iter)->get_name()
-               << "', " << ((*f_iter)->is_oneway() ? "TMessageType::ONEWAY" : "TMessageType::CALL")
+               << "', " << ((*f_iter)->is_oneway() ? "Thrift::TMessageType::ONEWAY" : "Thrift::TMessageType::CALL")
                << ", $self->{seqid});" << endl;
 
     f_service_ << indent() << "my $args = new " << argsname << "();" << endl;
@@ -1132,8 +1134,8 @@ void t_perl_generator::generate_service_client(t_service* tservice) {
                  << indent() << "my $mtype = 0;" << endl << endl;
 
       f_service_ << indent() << "$self->{input}->readMessageBegin(\\$fname, \\$mtype, \\$rseqid);"
-                 << endl << indent() << "if ($mtype == TMessageType::EXCEPTION) {" << endl
-                 << indent() << "  my $x = new TApplicationException();" << endl << indent()
+                 << endl << indent() << "if ($mtype == Thrift::TMessageType::EXCEPTION) {" << endl
+                 << indent() << "  my $x = new Thrift::TApplicationException();" << endl << indent()
                  << "  $x->read($self->{input});" << endl << indent()
                  << "  $self->{input}->readMessageEnd();" << endl << indent() << "  die $x;" << endl
                  << indent() << "}" << endl;
@@ -1644,30 +1646,30 @@ string t_perl_generator::type_to_enum(t_type* type) {
     case t_base_type::TYPE_VOID:
       throw "NO T_VOID CONSTRUCT";
     case t_base_type::TYPE_STRING:
-      return "TType::STRING";
+      return "Thrift::TType::STRING";
     case t_base_type::TYPE_BOOL:
-      return "TType::BOOL";
+      return "Thrift::TType::BOOL";
     case t_base_type::TYPE_I8:
-      return "TType::BYTE";
+      return "Thrift::TType::BYTE";
     case t_base_type::TYPE_I16:
-      return "TType::I16";
+      return "Thrift::TType::I16";
     case t_base_type::TYPE_I32:
-      return "TType::I32";
+      return "Thrift::TType::I32";
     case t_base_type::TYPE_I64:
-      return "TType::I64";
+      return "Thrift::TType::I64";
     case t_base_type::TYPE_DOUBLE:
-      return "TType::DOUBLE";
+      return "Thrift::TType::DOUBLE";
     }
   } else if (type->is_enum()) {
-    return "TType::I32";
+    return "Thrift::TType::I32";
   } else if (type->is_struct() || type->is_xception()) {
-    return "TType::STRUCT";
+    return "Thrift::TType::STRUCT";
   } else if (type->is_map()) {
-    return "TType::MAP";
+    return "Thrift::TType::MAP";
   } else if (type->is_set()) {
-    return "TType::SET";
+    return "Thrift::TType::SET";
   } else if (type->is_list()) {
-    return "TType::LIST";
+    return "Thrift::TType::LIST";
   }
 
   throw "INVALID TYPE IN type_to_enum: " + type->get_name();

lib/perl/Makefile.PL

@@ -18,15 +18,14 @@
 #
 
 use ExtUtils::MakeMaker;
-WriteMakefile( NAME => 'Thrift',
-               VERSION_FROM => 'lib/Thrift.pm',
-               MIN_PERL_VERSION => '5.006',
+WriteMakefile( ABSTRACT => 'Apache Thrift is a software framework for scalable cross-language services development.',
+               AUTHOR => 'Apache Thrift <dev@thrift.apache.org>',
+               LICENSE => 'apache_2_0',
+               MIN_PERL_VERSION => '5.010000',
+               NAME => 'Thrift',
+               NEEDS_LINKING => 0,
                PREREQ_PM => {
-                   'Bit::Vector' => 0,
-                   'Class::Accessor' => 0,
-                   'IO::Socket::INET' => 0
+                   'Bit::Vector'     => 0,
+                   'Class::Accessor' => 0
                },
-               ($] >= 5.006 ?
- (                AUTHOR => 'Apache Thrift <dev@thrift.apache.org>') : ()),
-               );
-
+               VERSION_FROM => 'lib/Thrift.pm' );

lib/perl/README.md

@@ -1,7 +1,13 @@
 Thrift Perl Software Library
 
-License
-=======
+# Summary
+
+Apache Thrift is a software framework for scalable cross-language services development.
+It combines a software stack with a code generation engine to build services that work
+efficiently and seamlessly between many programming languages.  A language-neutral IDL
+is used to generate functioning client libraries and server-side handling frameworks.
+
+# License
 
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements. See the NOTICE file
@@ -20,23 +26,13 @@ KIND, either express or implied. See the License for the
 specific language governing permissions and limitations
 under the License.
 
-Summary
-=======
-
-Apache Thrift is a software framework for scalable cross-language services development.
-It combines a software stack with a code generation engine to build services that work
-efficiently and seamlessly between many programming languages.  A language-neutral IDL
-is used to generate functioning client libraries and server-side handling frameworks.
-
-For More Information
-====================
+# For More Information
 
 See the [Apache Thrift Web Site](http://thrift.apache.org/) for more information.
 
-Using Thrift with Perl
-======================
+# Using Thrift with Perl
 
-Thrift requires Perl >= 5.6.0
+Thrift requires Perl >= 5.10.0
 
 Unexpected exceptions in a service handler are converted to
 TApplicationException with type INTERNAL ERROR and the string
@@ -55,12 +51,74 @@ a custom SIGCHLD handler within a thrift handler implementation
 as the ForkingServer resets the forked child process to use
 default signal handling.
 
-Dependencies
-============
+# Dependencies
+
+The following modules are not provided by Perl 5.10.0 but are required
+to use Thrift.
+
+## Runtime
+
+  * Bit::Vector
+  * Class::Accessor
+
+### HttpClient Transport
+
+These are only required if using Thrift::HttpClient:
+
+  * HTTP::Request
+  * IO::String
+  * LWP::UserAgent
+
+### SSL/TLS
+
+These are only required if using Thrift::SSLSocket or Thrift::SSLServerSocket:
+
+  * IO::Socket::SSL
+
+# Breaking Changes
+
+## 0.10.0
+
+The socket classes were refactored in 0.10.0 so that there is one package per
+file.  This means `use Socket;` no longer defines SSLSocket.  You can use this
+technique to make your application run against 0.10.0 as well as earlier versions:
+
+`eval { require Thrift::SSLSocket; } or do { require Thrift::Socket; }`
+
+## 0.11.0
+
+  * Namespaces of packages that were not scoped within Thrift have been fixed.
+  ** TApplicationException is now Thrift::TApplicationException
+  ** TException is now Thrift::TException
+  ** TMessageType is now Thrift::TMessageType
+  ** TProtocolException is now Thrift::TProtocolException
+  ** TProtocolFactory is now Thrift::TProtocolFactory
+  ** TTransportException is now Thrift::TTransportException
+  ** TType is now Thrift::TType
+
+If you need a single version of your code to work with both older and newer thrift
+namespace changes, you can make the new, correct namespaces behave like the old ones
+in your files with this technique to create an alias, which will allow you code to
+run against either version of the perl runtime for thrift:
+
+`BEGIN {*TType:: = *Thrift::TType::}`
+
+  * Packages found in Thrift.pm were moved into the Thrift/ directory in separate files:
+  ** Thrift::TApplicationException is now in Thrift/Exception.pm
+  ** Thrift::TException is now in Thrift/Exception.pm
+  ** Thrift::TMessageType is now in Thrift/MessageType.pm
+  ** Thrift::TType is now in Thrift/Type.pm
+
+If you need to modify your code to work against both older or newer thrift versions,
+you can deal with these changes in a backwards compatible way in your projects using eval:
+
+`eval  { require Thrift::Exception; require Thrift::MessageType; require Thrift::Type; }
+ or do { require Thrift; }`
+
+# Deprecations
+
+## 0.11.0
+
+Thrift::HttpClient setRecvTimeout() and setSendTimeout() are deprecated. 
+Use setTimeout instead.
 
-Bit::Vector       - comes with modern perl installations.
-Class::Accessor
-IO::Socket::INET  - comes with modern perl installations.
-IO::Socket::SSL   - required if using SSL/TLS.
-NET::SSLeay
-Crypt::SSLeay     - for make cross