Introduction
Several months back I posted my BSP Developer's Journal Part XVI - Using the BTF Editor. This weblog focused on the BTF editor and its use, particularly within the BSP area. Then last week by request, I revisited the BTF subject by providing an example of BSP: BTF editor example, Non Model View Controller. A question came from this weblog posting about how to save the content that is created in the BTF Editor. That is the topic that I would like to discuss today.
The example use of BTF that I want to talk about today is basically using it as a replacement for the traditional R/3 Long Text Object. At my company I have built table structures and configuration that mirror the setup of the R/3 Long Text but designed instead for holding BTF content. Similar to the R/3 Function Group STXD, I have created an ABAP Class for easy access to and manipulation of these BTF texts. Now although my weblogs about BTF in the past have focused on BTF in BSP, I want to point out that this solution can be used in either BSP applications or standard ABAP transactions.
To give you an idea of what this solution entails before we even start, I show the Object List of all items in my BTF Framework Package:
Database Layout
The BTF objects provided by SAP don't provide any real means for storing the resulting content in relation to the business objects they are connected to. This gives the BTF technology considerable flexibility, but also means that we need to create structures for storing this content ourselves. Just like in R/3 Long Text, I am going to start by categorizing my text objects by a Business Object and a Text ID. I wanted to create my own set of configuration tables with different values from the R/3 ones. To do this I first created Domains and Data Elements for my Object, Text ID, and their descriptions. I then created language independent configuration tables for each element. The following are what those tables look like:
Application Object Config Table
Text Id Config Table
Table Maintenance
I guess I am making an assumption that my readers are already aware of how to create language independent configuration tables since I am not going into great detail on this topic. I will include this screenshot that details the special foreign key relationship that exists between the ID only table and the ID + Description table.
My next step is to create a maintenance view for each pair of tables. I then generate table maintenance for the maintenance view. The following is what one of the maintenance views look like:
After all this is said and done, we are ready to use the generated table maintenance to setup our test data. The following are the entries that I setup for testing:
Text Table
Last but not least, we need a place to store the text objects themselves. I created a simple transparent table, once again modeled off the R/3 Long text tables. For keys we have our application object, text ID, language, and a business key (named BTF_NAME). For instance, this business key might be the concatenation of Purchase Order Number and Purchase Order Line Item. The main difference between my table and the R/3 one is that I am going to store my text as a single binary string in the database.
Exceptions
Now that we are done talking about the boring old database stuff, we can move on to the much more exciting technologies aspects. We will start off by looking at my exception class. If you need a nice tutorial on class based exceptions, I suggest that you check out the following weblog series by Thomas Weiss:
Message Class
I chose to go with an exception class that was Message Class based. Therefore when I first generated my class I received the IF_T100_MESSAGE interface. This allows me to link my exception tests directly to my message class. The following is a screen shot of my message class with all the message that I will eventually link to my exception class.
Exception Class Definition
Now you can see the properties and interfaces on my Exception class itself. Notice the IF_T100_MESSAGE interface that I mentioned earlier.
Exception Class Attributes
Now I know that I am going to have a few values that I will want to dynamically pass into my exception messages. Therefore I need to define public attributes in my Exception Class for these values. I ended up with attributes for Object, Text ID, and Object Name.
Exception IDs
Next up we will create the individual text IDs. This is where the Exception class has a special Texts tab. From here we can create new Exception IDs, link them to a message class object, and assign exception class attributes to the variables in our message.
Sample Code for raising our Exception
Well this is getting a little ahead of ourselves, but I thought it would be appropriate to show a little sample code for raising one of these exceptions. Later in the coding of the main class itself, you will see plenty of these examples.
You can see that we are able to fill the public attributes of our exception class during the raise exception itself. We are also able to specify which text id we want to trigger because each one can be identified via a generated public constant in the exception class.
Persistent Class
Writing SQL code is so 2004. Therefore I decided to code my database access using an ABAP Persistent Class. If you want a little background on Persistent Classes, have a look at ABAP Persistent Classes: Coding without SQL. ABAP has a nice graphical persistent class generator. You get a visual view of the source database table. You then choose the fields that you want to expose through the persistent class. When you activate the persistent class, get and set methods are generated for each field in the chosen database table. It also generates an Actor and Base Class. The following is a screen shot of the Persistent Class Builder:
Framework Class
We are ready to start looking at the Framework class itself. If you look at the next screen shot, you can see that this is fairly basic application class. However I did add the IF_SERIALIZABLE_OBJECT interface to this class. You will see later that we will have static methods for this class to help with serialization/deserialization of itself. This can be helpful if would want to use this class in a stateless BSP application as show in WebService Navigator Page for ABAP and Java.
Class Properties
Class Attributes
The attributes of our class are all Private but one - the BTF Document Object itself (which is necessary to a pass a reference of the document object into the BTF Editor). I do have an editor object attribute for the SAPGui. This is really only included for a couple of example/test methods I will have in my class. Because the BTF Editor itself is implemented differently depending upon if you are using SAPGui or BSP, I decided to leave all this functionality up to the consuming application.
Methods
The following is a listing of all the methods implemented in this class. I hope to have exposed all the methods one would need in working with BTF. I have reading, saving, deleting, etc. methods. In addition I have a few methods for testing and example, such as the download, display in IE, and display in Editor methods.
Constructor
In our constructor we receive and validate our text objects. If everything checks out we will also initialize the BTF Document object.
GET_CURRENT_KEYS
Since all the object keys are stored as private attributes of our class, we need a public method that will give us read only access to these keys. That is exactly what this method is for.
GET_ENCODING_FROM_LANGUAGE
This is a static helper class. If a consuming application doesn't want to use the default character encoding of Unicode (utf-8), then they should probably use the encoding that matches the logon language. This method can be called to lookup this proper encoding for you.
INITIALIZE_BTF
This method contains the code to get a reference to the BTF Main class and use it create a reference to a BTF Document object.
INTIALIZE_DOCUMENT
If your application wants to be able to set an initial string into an empty BTF document, this is the method it could use. You can pass the initial text in as a plain string and this method will take care of casting it into the binary string.
READ_TEXT
This critical method will use the persistent object to read the BTF Content from the database. It then decompresses the content and passes it to the BTF Document Object.
SAVE_TEXT
Equally important is our SAVE_TEXT method. This method will retrieve the BTF Content from the Document Object, compress it, and then use the persistent object to write it back into the database. Please note that an application object that uses this method, must follow this call with a commit work for the data base updates to actually be performed.
CREATE_TEXT
Obviously we need a way to create new text objects as well. Here we will validate that the business object name is valid, then initialize the BTF document, and finally create a new persistent object instance.
DELETE_TEXT
To complete our quartet of obvious methods, we have the ever popular method to delete a text object. The code here is really quite simple because we use the persistent object to delete the database entries. The same rule about Commit Work from the Save method applies here as well.
SERIALIZE_ME
Now we come to the serialization/deserialization static methods. This helper method takes in an instance of the same class and serializes it XML. Like we said before this provides interesting persistence options for stateless BSP applications. Now earlier I added the IF_SERIALIZABLE_OBJECT interface to my persistent class as well. Therefore this inner object reference will be serialized/deserialized as well.
DESERIALIZE_ME
Just the opposite as the Serialize class. However the BTF objects didn't have the IF_SERIALIZABLE_OBJECT interface so their object instance was lost. Therefore we will restore them in this method with a little bit of code.
DOWNLOAD_BTF_TEXT
Now we come to a set of methods that aren't really designed to be consumed by a calling application. There are really only here for testing and to serve as example code (consequently, they don't do quite as good a job of error handling as the rest of the class). Also because these methods interact with the User's Front end through the SAPGui framework, you would never be able to call these from BSP. This first one will download the content of the BTF Document to your front end.
VIEW_BTF_TEXT
This method downloads the BTF and starts up your browser for viewing it.
EDIT_BTF_TEXT
This method will load the current BTF Document content into a SAPGui based BTF editor. This editor will open in a control based dialog box.
ON_DIALOGBOX_CLOSE
Our final method serves as an event handler for the CLOSE event of the CL_GUI_DIALOGBOX_CONTAINER class. If you are interested in how to code Control Framework event handlers in Global ABAP Object classes, I suggest ABAP OO mixed with Classic Dynpro
The ABAP Unit Class
The other day it was suggested that I should look into the ABAP Unit functionality for Unit Testing. As I was looking over this class in preparation for writing this weblog, I thought it might be the perfect opportunity to write my first ABAP Unit Class. It took me about 3 and half hours to create this Unit testing class. However a good portion of that time was spent on research. I read the online help and several weblogs on SDN that I found by searching on "ABAP Unit". I also did a good amount of trial and error coding. The end result is that I ended up with 4 test methods. The first one tests the proper initialization of the class including reading/writing content to/from the database with the persistent object. The second method tests my static method for loading encoding type by language. The third method tests the serialization/deserialization functionality. And the final method tests create and delete.
The ABAP Unit Class Definition
If you aren't familiar with ABAP Unit, this is simply another type of ABAP Object Class. It is declared as a local class in the object that you want to test. Therefore this is a local class, lcl_my_unit_test, housed in my global class, ZCL_ES_BTF_FRAMEWORK. The following is the definition of my test class.
The ABAP Unit Class Implementation
This is where the little bit of test data that I first setup in the weblog comes in handy. We will setup test conditions for a small amount of data that I preloaded into the development system. Since Unit Tests are only designed to run in a development system, we can predict that this data will be there. You will definitely want to have a look at the class cl_aunit_assert. This class contains all the comparison methods that really make up ABAP Unit. The best advice I can give you for writing an ABAP Unit class is to just have at it. I learned tons by making mistakes while trying to create this class. I'm sure that my ABAP Unit classes will get better as I write more of them.
The ABAP Unit Use
Executing the ABAP Unit test is really quite simple. It can be ran from the test options in SE80 or as part of the Code Inspector (transaction SCI). The following shows one menu path to reach the Unit Test.
If your unit test passes, you receive a status message to that effect. However I wanted to demonstrate the screens you see when a test condition fails. That turned out to be not that difficult. The first time I executed my Unit Test after adding it to my class, I actually failed on a valid condition I had never caught before. The following are some screen shots of the test failure screens.
Closing
For those of you who are interested in putting the BTF technology to work, I hope this weblog will serve as one more example to learn from. Even if you aren't interested in BTF, I hope that you took away some learnings on persistent objects or maybe even ABAP Unit.
Several months back I posted my BSP Developer's Journal Part XVI - Using the BTF Editor. This weblog focused on the BTF editor and its use, particularly within the BSP area. Then last week by request, I revisited the BTF subject by providing an example of BSP: BTF editor example, Non Model View Controller. A question came from this weblog posting about how to save the content that is created in the BTF Editor. That is the topic that I would like to discuss today.
The example use of BTF that I want to talk about today is basically using it as a replacement for the traditional R/3 Long Text Object. At my company I have built table structures and configuration that mirror the setup of the R/3 Long Text but designed instead for holding BTF content. Similar to the R/3 Function Group STXD, I have created an ABAP Class for easy access to and manipulation of these BTF texts. Now although my weblogs about BTF in the past have focused on BTF in BSP, I want to point out that this solution can be used in either BSP applications or standard ABAP transactions.
To give you an idea of what this solution entails before we even start, I show the Object List of all items in my BTF Framework Package:
Database Layout
The BTF objects provided by SAP don't provide any real means for storing the resulting content in relation to the business objects they are connected to. This gives the BTF technology considerable flexibility, but also means that we need to create structures for storing this content ourselves. Just like in R/3 Long Text, I am going to start by categorizing my text objects by a Business Object and a Text ID. I wanted to create my own set of configuration tables with different values from the R/3 ones. To do this I first created Domains and Data Elements for my Object, Text ID, and their descriptions. I then created language independent configuration tables for each element. The following are what those tables look like:
Application Object Config Table
Text Id Config Table
Table Maintenance
I guess I am making an assumption that my readers are already aware of how to create language independent configuration tables since I am not going into great detail on this topic. I will include this screenshot that details the special foreign key relationship that exists between the ID only table and the ID + Description table.
My next step is to create a maintenance view for each pair of tables. I then generate table maintenance for the maintenance view. The following is what one of the maintenance views look like:
After all this is said and done, we are ready to use the generated table maintenance to setup our test data. The following are the entries that I setup for testing:
Text Table
Last but not least, we need a place to store the text objects themselves. I created a simple transparent table, once again modeled off the R/3 Long text tables. For keys we have our application object, text ID, language, and a business key (named BTF_NAME). For instance, this business key might be the concatenation of Purchase Order Number and Purchase Order Line Item. The main difference between my table and the R/3 one is that I am going to store my text as a single binary string in the database.
Exceptions
Now that we are done talking about the boring old database stuff, we can move on to the much more exciting technologies aspects. We will start off by looking at my exception class. If you need a nice tutorial on class based exceptions, I suggest that you check out the following weblog series by Thomas Weiss:
- The New Class-Based Exception Handling in ABAP - Part 1
- The New Class-Based Exception Handling in ABAP - Part 2
- The New Class-Based Exception Handling in ABAP - Part 3
Message Class
I chose to go with an exception class that was Message Class based. Therefore when I first generated my class I received the IF_T100_MESSAGE interface. This allows me to link my exception tests directly to my message class. The following is a screen shot of my message class with all the message that I will eventually link to my exception class.
Exception Class Definition
Now you can see the properties and interfaces on my Exception class itself. Notice the IF_T100_MESSAGE interface that I mentioned earlier.
Exception Class Attributes
Now I know that I am going to have a few values that I will want to dynamically pass into my exception messages. Therefore I need to define public attributes in my Exception Class for these values. I ended up with attributes for Object, Text ID, and Object Name.
Exception IDs
Next up we will create the individual text IDs. This is where the Exception class has a special Texts tab. From here we can create new Exception IDs, link them to a message class object, and assign exception class attributes to the variables in our message.
Sample Code for raising our Exception
Well this is getting a little ahead of ourselves, but I thought it would be appropriate to show a little sample code for raising one of these exceptions. Later in the coding of the main class itself, you will see plenty of these examples.
raise exception type zcx_es_btf_framework
exporting btf_name = me->btf_name
btf_object = me->btf_object
btf_id = me->btf_tdid
textid = zcx_es_btf_framework=>zcs_es_btf_name_doesnt_exists.You can see that we are able to fill the public attributes of our exception class during the raise exception itself. We are also able to specify which text id we want to trigger because each one can be identified via a generated public constant in the exception class.
Persistent Class
Writing SQL code is so 2004. Therefore I decided to code my database access using an ABAP Persistent Class. If you want a little background on Persistent Classes, have a look at ABAP Persistent Classes: Coding without SQL. ABAP has a nice graphical persistent class generator. You get a visual view of the source database table. You then choose the fields that you want to expose through the persistent class. When you activate the persistent class, get and set methods are generated for each field in the chosen database table. It also generates an Actor and Base Class. The following is a screen shot of the Persistent Class Builder:
Framework Class
We are ready to start looking at the Framework class itself. If you look at the next screen shot, you can see that this is fairly basic application class. However I did add the IF_SERIALIZABLE_OBJECT interface to this class. You will see later that we will have static methods for this class to help with serialization/deserialization of itself. This can be helpful if would want to use this class in a stateless BSP application as show in WebService Navigator Page for ABAP and Java.
Class Properties
Class Attributes
The attributes of our class are all Private but one - the BTF Document Object itself (which is necessary to a pass a reference of the document object into the BTF Editor). I do have an editor object attribute for the SAPGui. This is really only included for a couple of example/test methods I will have in my class. Because the BTF Editor itself is implemented differently depending upon if you are using SAPGui or BSP, I decided to leave all this functionality up to the consuming application.
Methods
The following is a listing of all the methods implemented in this class. I hope to have exposed all the methods one would need in working with BTF. I have reading, saving, deleting, etc. methods. In addition I have a few methods for testing and example, such as the download, display in IE, and display in Editor methods.
Constructor
In our constructor we receive and validate our text objects. If everything checks out we will also initialize the BTF Document object.
method constructor.
*@78QImporting@ I_OBJECT TYPE ZZES_BTF_TTXOB BTF Texts: application object
*@78QImporting@ I_TDID TYPE ZZES_BTF_TDID Text ID
*@78QImporting@ I_NAME TYPE TDOBNAME OPTIONAL Name
*@78QImporting@ I_SPRAS TYPE SPRAS DEFAULT SY-LANGU Language Key
*@78QImporting@ I_ENCODING TYPE CSEQUENCE DEFAULT 'utf-8' Character Encoding
*@03QException@ CX_BTF_RUNTIME_ERROR BTF Exception: Runtime Error
*@03QException@ ZCX_ES_BTF_FRAMEWORK Exception Class for BTF Framework
****Set Keys
btf_name = i_name.
btf_object = i_object.
btf_spras = i_spras.
btf_tdid = i_tdid.
btf_encoding = i_encoding.
****Check Object
data: l_btf_obj like me->btf_object.
select single btf_obj from zes_btf_obj into l_btf_obj
where btf_obj = me->btf_object.
if sy-subrc ne 0.
raise exception type zcx_es_btf_framework
exporting btf_object = me->btf_object
textid = zcx_es_btf_framework=>zcx_es_btf_object_error.
endif.
****Check ID
data: l_btf_id like me->btf_tdid.
select single btf_id from zes_btf_id into l_btf_id
where btf_id = me->btf_tdid. if sy-subrc ne 0.
raise exception type zcx_es_btf_framework
exporting btf_id = me->btf_tdid
textid = zcx_es_btf_framework=>zcx_es_btf_id_error.
endif.
****Check Combinatin of ID and Object
select single btf_id from zes_btf_id into l_btf_id
where btf_obj = me->btf_object
and btf_id = me->btf_tdid.
if sy-subrc ne 0.
raise exception type zcx_es_btf_framework
exporting btf_id = me->btf_tdid
btf_object = me->btf_object
textid = zcx_es_btf_framework=>zcx_es_btf_id_object_match.
endif.
****Initialize BTF
me->initialize_btf( ).
endmethod.GET_CURRENT_KEYS
Since all the object keys are stored as private attributes of our class, we need a public method that will give us read only access to these keys. That is exactly what this method is for.
method get_current_keys.
*@79QExporting@ E_OBJECT TYPE ZZES_BTF_TTXOB BTF Texts: application object
*@79QExporting@ E_TDID TYPE ZZES_BTF_TDID Text ID
*@79QExporting@ E_NAME TYPE TDOBNAME Name
*@79QExporting@ E_SPRAS TYPE SPRAS Language Key
*@79QExporting@ E_ENCODING TYPE STRING Character Encoding
e_object = btf_object.
e_tdid = btf_tdid.
e_name = btf_name.
e_spras = btf_spras.
e_encoding = btf_encoding.
endmethod.GET_ENCODING_FROM_LANGUAGE
This is a static helper class. If a consuming application doesn't want to use the default character encoding of Unicode (utf-8), then they should probably use the encoding that matches the logon language. This method can be called to lookup this proper encoding for you.
method get_encoding_from_language.
*@78QImporting@ I_SPRAS TYPE SPRAS DEFAULT SY-LANGU Language Key
*@7BQReturning@ VALUE( R_ENCODING ) TYPE STRING Character Encoding
constants: kind type cpattrkind value 'H'.
data: codepage type cpcodepage.
****Get Code Page for the language
call function 'SCP_CODEPAGE_FOR_LANGUAGE'
exporting
language = i_spras
importing
codepage = codepage
exceptions
no_codepage = 1
others = 2.
if sy-subrc <> 0.
r_encoding = 'utf-8'.
exit.
endif.
****Get the encoding for the Code Page
select single cpattr from tcp00a into r_encoding
where cpcodepage = codepage
and cpattrkind = kind.
if r_encoding is initial.
r_encoding = 'utf-8'.
endif.
endmethod.INITIALIZE_BTF
This method contains the code to get a reference to the BTF Main class and use it create a reference to a BTF Document object.
method initialize_btf.
*@03QException@ CX_BTF_RUNTIME_ERROR BTF Exception: Runtime Error
****Create BTF Master Object
btf = cl_btf=>get_reference( ).
****Create an Empty BTF Document
document = btf->create_document( btf_spras ).
endmethod.INTIALIZE_DOCUMENT
If your application wants to be able to set an initial string into an empty BTF document, this is the method it could use. You can pass the initial text in as a plain string and this method will take care of casting it into the binary string.
method intialize_document.
*@78QImporting@ I_TEXT TYPE STRING OPTIONAL Initialization Text
*@03QException@ ZCX_ES_BTF_FRAMEWORK Exception Class for BTF Framework
*@03QException@ CX_BTF_RUNTIME_ERROR BTF Exception: Runtime Error
*@03QException@ CX_BTF_PARAMETER_ERROR BTF Exception: Parameter Error
data x_text type xstring.
if document is initial.
raise exception type zcx_es_btf_framework
exporting textid = zcx_es_btf_framework=>zcx_es_btf_id_doc_init.
endif.
call function 'SCMS_STRING_TO_XSTRING'
exporting
text = i_text
importing
buffer = x_text
exceptions
failed = 1
others = 2.
if sy-subrc <> 0.
raise exception type zcx_es_btf_framework
exporting textid = zcx_es_btf_framework=>zcs_es_btf_content_cast.
endif.
document->set_content( text = x_text
encoding = btf_encoding ).
endmethod.READ_TEXT
This critical method will use the persistent object to read the BTF Content from the database. It then decompresses the content and passes it to the BTF Document Object.
method read_text.
*@03QException@ ZCX_ES_BTF_FRAMEWORK Exception Class for BTF Framework
*@03QException@ CX_PARAMETER_INVALID_RANGE Parameter with Invalid Range
*@03QException@ CX_SY_BUFFER_OVERFLOW System Exception: Buffer too Short
*@03QException@ CX_SY_COMPRESSION_ERROR System Exception: Compression Error
*@03QException@ CX_BTF_RUNTIME_ERROR BTF Exception: Runtime Error
*@03QException@ CX_BTF_PARAMETER_ERROR BTF Exception: Parameter Error
****Load the Persistent Object
clear btf_content.
try.
btf_content = zca_es_pers_zes_btf_content=>agent->get_persistent(
i_btf_obj = me->btf_object
i_btf_id = me->btf_tdid
i_btf_spras = me->btf_spras
i_btf_name = me->btf_name ).
catch cx_os_object_not_found.
raise exception type zcx_es_btf_framework
exporting btf_name = me->btf_name
btf_object = me->btf_object
btf_id = me->btf_tdid
textid = zcx_es_btf_framework=>zcs_es_btf_name_doesnt_exists.
endtry.
me->content = btf_content->get_btf_content( ).
****Un-Compress the Object
if me->content is not initial.
call method cl_abap_gzip=>decompress_binary
exporting
gzip_in = me->content
importing
raw_out = me->content.
endif.
****Set Content into the BTF Document
if document is initial.
raise exception type zcx_es_btf_framework
exporting textid = zcx_es_btf_framework=>zcx_es_btf_id_doc_init.
endif.
data: l_encoding type string.
l_encoding = btf_content->get_encoding( ).
document->set_content( text = me->content
encoding = l_encoding ).
endmethod.SAVE_TEXT
Equally important is our SAVE_TEXT method. This method will retrieve the BTF Content from the Document Object, compress it, and then use the persistent object to write it back into the database. Please note that an application object that uses this method, must follow this call with a commit work for the data base updates to actually be performed.
method save_text.
*@03QException@ ZCX_ES_BTF_FRAMEWORK Exception Class for BTF Framework
*@03QException@ CX_PARAMETER_INVALID_RANGE Parameter with Invalid Range
*@03QException@ CX_SY_BUFFER_OVERFLOW System Exception: Buffer too Short
*@03QException@ CX_SY_COMPRESSION_ERROR System Exception: Compression Error
*@03QException@ CX_BTF_RUNTIME_ERROR BTF Exception: Runtime Error
*@03QException@ CX_BTF_PARAMETER_ERROR BTF Exception: Parameter Error
****Get the Content from the BTF Document
if document is initial.
raise exception type zcx_es_btf_framework
exporting textid = zcx_es_btf_framework=>zcx_es_btf_id_doc_init.
endif.
document->get_content( importing
text = me->content ).
****Uncompress the Content
call method cl_abap_gzip=>compress_binary
exporting
raw_in = me->content
importing
gzip_out = me->content.
****Setup the Persistent Object
btf_content->set_btf_content( me->content ).
btf_content->set_btf_uuser( sy-uname ).
btf_content->set_btf_udate( sy-datum ).
btf_content->set_btf_utime( sy-uzeit ).
endmethod.CREATE_TEXT
Obviously we need a way to create new text objects as well. Here we will validate that the business object name is valid, then initialize the BTF document, and finally create a new persistent object instance.
method create_text.
*@78QImporting@ I_NAME TYPE TDOBNAME
*@78QImporting@ I_TEXT TYPE STRING
*@03QException@ ZCX_ES_BTF_FRAMEWORK Exception Class for BTF Framework
*@03QException@ CX_BTF_RUNTIME_ERROR BTF Exception: Runtime Error
*@03QException@ CX_BTF_PARAMETER_ERROR BTF Exception: Parameter Error
****Is the Text Name already specified in the object
if btf_name is not initial.
raise exception type zcx_es_btf_framework
exporting btf_name = me->btf_name
textid = zcx_es_btf_framework=>zcs_es_btf_name_spec.
endif.
****Where we given a duplicate Name?
data: l_btf_id like me->btf_tdid.
select single btf_id from zes_btf_content into l_btf_id
where btf_obj = me->btf_object
and btf_id = me->btf_tdid
and btf_spras = me->btf_spras
and btf_name = i_name.
if sy-subrc = 0.
raise exception type zcx_es_btf_framework
exporting btf_name = i_name
btf_object = me->btf_object
btf_id = me->btf_tdid
textid = zcx_es_btf_framework=>zcs_es_btf_name_exists.
endif.
****Set Parameters and intialize the BTF Document
clear me->content.
me->btf_name = i_name.
me->intialize_document( i_text ).
****Initialize the Persistent Object
clear btf_content.
try.
data: l_encoding type cpattr.
l_encoding = me->btf_encoding.
btf_content = zca_es_pers_zes_btf_content=>agent->create_persistent(
i_btf_obj = me->btf_object
i_btf_id = me->btf_tdid
i_btf_spras = me->btf_spras
i_btf_name = me->btf_name
i_btf_user = sy-uname
i_btf_date = sy-datum
i_btf_time = sy-uzeit
i_encoding = l_encoding
i_btf_content = me->content ).
catch cx_os_object_existing.
raise exception type zcx_es_btf_framework
exporting btf_name = me->btf_name
btf_object = me->btf_object
btf_id = me->btf_tdid
textid = zcx_es_btf_framework=>zcs_es_btf_name_exists.
endtry.
endmethod.DELETE_TEXT
To complete our quartet of obvious methods, we have the ever popular method to delete a text object. The code here is really quite simple because we use the persistent object to delete the database entries. The same rule about Commit Work from the Save method applies here as well.
method delete_text.
*@03QException@ ZCX_ES_BTF_FRAMEWORK Exception Class for BTF Framework
try.
zca_es_pers_zes_btf_content=>agent->delete_persistent(
i_btf_obj = me->btf_object
i_btf_id = me->btf_tdid
i_btf_spras = me->btf_spras
i_btf_name = me->btf_name ).
catch cx_os_object_not_existing.
raise exception type zcx_es_btf_framework
exporting btf_name = me->btf_name
btf_object = me->btf_object
btf_id = me->btf_tdid
textid = zcx_es_btf_framework=>zcs_es_btf_name_doesnt_exists.
endtry.
endmethod.SERIALIZE_ME
Now we come to the serialization/deserialization static methods. This helper method takes in an instance of the same class and serializes it XML. Like we said before this provides interesting persistence options for stateless BSP applications. Now earlier I added the IF_SERIALIZABLE_OBJECT interface to my persistent class as well. Therefore this inner object reference will be serialized/deserialized as well.
method serialize_me.
*@78QImporting@ I_ME TYPE REF TO ZCL_ES_BTF_FRAMEWORK Kimball BTF Text Framework
*@7BQReturning@ VALUE( R_XML ) TYPE XSTRING
*@03QException@ CX_XSLT_EXCEPTION XSLT Exception
call transformation id
source model = i_me
result xml r_xml
options
data_refs = 'embedded'.
endmethod.DESERIALIZE_ME
Just the opposite as the Serialize class. However the BTF objects didn't have the IF_SERIALIZABLE_OBJECT interface so their object instance was lost. Therefore we will restore them in this method with a little bit of code.
method deserialize_me.
*@78QImporting@ I_XML TYPE XSTRING
*@7BQReturning@ VALUE( R_ME ) TYPE REF TO ZCL_ES_BTF_FRAMEWORK Kimball BTF Text Framework
call transformation id
source xml i_xml
result model = r_me.
r_me->initialize_btf( ).
endmethod.DOWNLOAD_BTF_TEXT
Now we come to a set of methods that aren't really designed to be consumed by a calling application. There are really only here for testing and to serve as example code (consequently, they don't do quite as good a job of error handling as the rest of the class). Also because these methods interact with the User's Front end through the SAPGui framework, you would never be able to call these from BSP. This first one will download the content of the BTF Document to your front end.
method download_btf_text.
*@78QImporting@ I_FILE TYPE CSEQUENCE
*@03QException@ ZCX_ES_BTF_FRAMEWORK Exception Class for BTF Framework
*@03QException@ CX_BTF_RUNTIME_ERROR BTF Exception: Runtime Error
*@03QException@ CX_BTF_PARAMETER_ERROR BTF Exception: Parameter Error
data: l_file type string.
l_file = i_file.
if l_file is initial.
data: l_filename type string,
l_path type string,
l_fullpath type string,
window_t type string.
window_t = 'Download BTF Text'(001).
call method cl_gui_frontend_services=>file_save_dialog
exporting
window_title = window_t
default_extension = 'HTM'
file_filter = 'HTML files (*.HTML, *.HTM)|*.HTML;*.HTM|'
changing
filename = l_filename
path = l_path
fullpath = l_fullpath
exceptions
cntl_error = 1
error_no_gui = 2
not_supported_by_gui = 3
others = 4.
if sy-subrc <> 0.
endif.
l_file = l_fullpath.
endif.
check l_file is not initial.
****Get the Content from the BTF Document
if document is initial.
raise exception type zcx_es_btf_framework
exporting textid = zcx_es_btf_framework=>zcx_es_btf_id_doc_init.
endif.
document->get_content( importing
text = me->content ).
types: t_data(255) type x.
data: data_tab type table of t_data.
call function 'SCMS_XSTRING_TO_BINARY'
exporting
buffer = me->content
tables
binary_tab = data_tab.
call method cl_gui_frontend_services=>gui_download
exporting
filename = l_file
filetype = 'BIN'
write_lf = ''
changing
data_tab = data_tab
exceptions
file_write_error = 1
no_batch = 2
gui_refuse_filetransfer = 3
invalid_type = 4
no_authority = 5
unknown_error = 6
header_not_allowed = 7
separator_not_allowed = 8
filesize_not_allowed = 9
header_too_long = 10
dp_error_create = 11
dp_error_send = 12
dp_error_write = 13
unknown_dp_error = 14
access_denied = 15
dp_out_of_memory = 16
disk_full = 17
dp_timeout = 18
file_not_found = 19
dataprovider_exception = 20
control_flush_error = 21
not_supported_by_gui = 22
error_no_gui = 23
others = 24.
if sy-subrc <> 0.
* MESSAGE ID SY-MSGID TYPE SY-MSGTY NUMBER SY-MSGNO
* WITH SY-MSGV1 SY-MSGV2 SY-MSGV3 SY-MSGV4.
endif.
endmethod.VIEW_BTF_TEXT
This method downloads the BTF and starts up your browser for viewing it.
method view_btf_text.
*@03QException@ ZCX_ES_BTF_FRAMEWORK Exception Class for BTF Framework
*@03QException@ CX_BTF_RUNTIME_ERROR BTF Exception: Runtime Error
*@03QException@ CX_BTF_PARAMETER_ERROR BTF Exception: Parameter Error
data: l_file type string.
data: temp_dir type string.
call method cl_gui_frontend_services=>get_temp_directory
changing
temp_dir = temp_dir
exceptions
cntl_error = 1
error_no_gui = 2
not_supported_by_gui = 3
others = 4.
if sy-subrc <> 0.
endif.
cl_gui_cfw=>flush( ).
concatenate temp_dir
' tf.html'
into l_file.
me->download_btf_text( l_file ).
call method cl_gui_frontend_services=>execute
exporting
document = l_file
exceptions
cntl_error = 1
error_no_gui = 2
bad_parameter = 3
file_not_found = 4
path_not_found = 5
file_extension_unknown = 6
error_execute_failed = 7
synchronous_failed = 8
not_supported_by_gui = 9
others = 10.
if sy-subrc <> 0.
endif.
cl_gui_cfw=>flush( ).
endmethod.EDIT_BTF_TEXT
This method will load the current BTF Document content into a SAPGui based BTF editor. This editor will open in a control based dialog box.
method edit_btf_text.
*@03QException@ ZCX_ES_BTF_FRAMEWORK Exception Class for BTF Framework
*@03QException@ CX_BTF_RUNTIME_ERROR BTF Exception: Runtime Error
*@03QException@ CX_BTF_PARAMETER_ERROR BTF Exception: Parameter Error
****Get the Content from the BTF Document
if document is initial.
raise exception type zcx_es_btf_framework
exporting textid = zcx_es_btf_framework=>zcx_es_btf_id_doc_init.
endif.
clear dialogbox.
create object dialogbox
exporting
* PARENT =
width = 30
height = 50
* STYLE =
* REPID =
* DYNNR =
* LIFETIME = lifetime_default
* TOP = 0
* LEFT = 0
* CAPTION =
* NO_AUTODEF_PROGID_DYNNR =
* METRIC = 0
* NAME =
exceptions
cntl_error = 1
cntl_system_error = 2
create_error = 3
lifetime_error = 4
lifetime_dynpro_dynpro_link = 5
event_already_registered = 6
error_regist_event = 7
others = 8.
if sy-subrc <> 0.
endif.
set handler me->on_dialogbox_close for
dialogbox.
try.
data: btf_system_exception type ref to cx_btf_system_error,
btf_exception_text type string.
data: design_mode type i.
clear btf_editor.
clear btf_editor_options.
design_mode = if_btf_editor_constants=>co_design_mode_on.
btf_editor = btf->create_editor( document ).
call method btf_editor->initialize
exporting
ctrl_parent = dialogbox
design_mode = design_mode.
btf_editor_options ?= btf_editor.
btf_editor_options->set_local_printing( if_btf_editor_options=>co_local_printing_on ).
btf_editor_options->set_local_operations( if_btf_editor_options=>co_local_operations_on ).
btf_editor_options->set_windows_fonts( if_btf_editor_options=>co_windows_fonts_on ).
catch cx_btf_system_error into btf_system_exception.
btf_exception_text = btf_system_exception->get_text( ).
if btf_system_exception->textid = cx_btf_system_error=>unsupported_gui_for_action.
message i208(00) with btf_exception_text.
else.
message e208(00) with btf_exception_text.
endif.
endtry.
endmethod.ON_DIALOGBOX_CLOSE
Our final method serves as an event handler for the CLOSE event of the CL_GUI_DIALOGBOX_CONTAINER class. If you are interested in how to code Control Framework event handlers in Global ABAP Object classes, I suggest ABAP OO mixed with Classic Dynpro
method on_dialogbox_close.
call method btf_editor->get_content( ).
document = btf_editor->get_document( ).
cl_gui_cfw=>flush( ).
call method document->get_content
importing
text = content.
btf_editor->free( ).
clear btf_editor.
free btf_editor.
call method dialogbox->free
exceptions
others = 1.
free dialogbox.
clear dialogbox.
endmethod.The ABAP Unit Class
The other day it was suggested that I should look into the ABAP Unit functionality for Unit Testing. As I was looking over this class in preparation for writing this weblog, I thought it might be the perfect opportunity to write my first ABAP Unit Class. It took me about 3 and half hours to create this Unit testing class. However a good portion of that time was spent on research. I read the online help and several weblogs on SDN that I found by searching on "ABAP Unit". I also did a good amount of trial and error coding. The end result is that I ended up with 4 test methods. The first one tests the proper initialization of the class including reading/writing content to/from the database with the persistent object. The second method tests my static method for loading encoding type by language. The third method tests the serialization/deserialization functionality. And the final method tests create and delete.
The ABAP Unit Class Definition
If you aren't familiar with ABAP Unit, this is simply another type of ABAP Object Class. It is declared as a local class in the object that you want to test. Therefore this is a local class, lcl_my_unit_test, housed in my global class, ZCL_ES_BTF_FRAMEWORK. The following is the definition of my test class.
class lcl_my_unit_test definition for testing.
private section.
methods test_init_class for testing.
methods test_encoding_from_lang for testing.
methods test_serialize for testing.
methods test_create_delete for testing.
endclass. "zcl_my_unit_test DEFINITIONThe ABAP Unit Class Implementation
This is where the little bit of test data that I first setup in the weblog comes in handy. We will setup test conditions for a small amount of data that I preloaded into the development system. Since Unit Tests are only designed to run in a development system, we can predict that this data will be there. You will definitely want to have a look at the class cl_aunit_assert. This class contains all the comparison methods that really make up ABAP Unit. The best advice I can give you for writing an ABAP Unit class is to just have at it. I learned tons by making mistakes while trying to create this class. I'm sure that my ABAP Unit classes will get better as I write more of them.
*---------------------------------------------------------------------*
* CLASS lcl_my_unit_test IMPLEMENTATION
*---------------------------------------------------------------------*
**---------------------------------------------------------------------*
class lcl_my_unit_test implementation.
method test_init_class.
data: btf type ref to zcl_es_btf_framework.
try.
create object btf
exporting
i_object = '640_TRAIN'
i_tdid = '0001'
i_name = 'TEST01'.
endtry.
data: l_object type zzes_btf_ttxob,
l_tdid type zzes_btf_tdid,
l_spras type spras,
l_name type tdobname,
l_encoding type string.
call method btf->get_current_keys
importing
e_object = l_object
e_tdid = l_tdid
e_name = l_name
e_spras = l_spras
e_encoding = l_encoding.
cl_aunit_assert=>assert_equals( act = l_object
exp = '640_TRAIN2'
msg = 'Incorrect BTF Text Object'(a03) ).
cl_aunit_assert=>assert_equals( act = l_tdid
exp = '0001'
msg = 'Incorrect BTF Text ID'(a04) ).
cl_aunit_assert=>assert_equals( act = l_name
exp = 'TEST01'
msg = 'Incorrect BTF Text Name'(a05) ).
cl_aunit_assert=>assert_equals( act = l_spras
exp = sy-langu
msg = 'Incorrect BTF Text Language'(a06) ).
cl_aunit_assert=>assert_equals( act = l_encoding
exp = 'utf-8'
msg = 'Incorrect BTF Text Encoding'(a07) ).
cl_aunit_assert=>assert_not_initial( act = btf->document
msg = 'BTF Document Object is initial'(a08) ).
btf->read_text( ).
data: l_text type string.
data: l_date(10) type c.
data: l_time(8) type c.
write sy-datum to l_date.
write sy-uzeit to l_time.
concatenate 'Unit Test Text inserted on'
l_date
l_time
'by'
sy-uname
into l_text
separated by space.
btf->intialize_document( l_text ).
btf->save_text( ).
commit work and wait.
data: icontent type zes_btf_content.
select single * from zes_btf_content into icontent
where btf_obj = '640_TRAIN'
and btf_id = '0001'
and btf_name = 'TEST01'
and btf_spras = sy-langu.
cl_aunit_assert=>assert_equals( act = icontent-encoding
exp = 'utf-8'
msg = 'BTF Encoding Not Set'(a20) ).
cl_aunit_assert=>assert_equals( act = icontent-btf_uuser
exp = sy-uname
msg = 'BTF Last Updated By Not Set'(a09) ).
cl_aunit_assert=>assert_equals( act = icontent-btf_udate
exp = sy-datum
msg = 'BTF Last Updated Date Not Set'(a10) ).
cl_aunit_assert=>assert_not_initial( act = icontent-btf_content
msg = 'BTF Content on Update is initial'(a16) ).
data: begin_time type syuzeit.
begin_time = sy-uzeit - 60.
if icontent-btf_utime < begin_time or
icontent-btf_utime > sy-uzeit.
cl_aunit_assert=>fail( msg = 'BTF Last Update Time is not within acceptable bounds'(a11) ).
endif.
* IF sy-batch IS INITIAL.
* CALL METHOD btf->view_btf_text( ).
* ENDIF.
endmethod. "test_init_class
method test_encoding_from_lang.
data: lang_latin1 type sylangu.
data: lang_latin2 type sylangu.
data: output_encode type string.
lang_latin1 = 'E'. "English
clear output_encode.
output_encode = zcl_es_btf_framework=>get_encoding_from_language( lang_latin1 ).
cl_aunit_assert=>assert_equals( act = output_encode
exp = 'iso-8859-1'
msg = 'Incorrect encoding for English'(a01) ).
lang_latin2 = 'L'. "Polish
clear output_encode.
output_encode = zcl_es_btf_framework=>get_encoding_from_language( lang_latin2 ).
cl_aunit_assert=>assert_equals( act = output_encode
exp = 'iso-8859-2'
msg = 'Incorrect encoding for Polish'(a02) ).
endmethod. "test_encoding_from_lang
method test_serialize.
data: btf type ref to zcl_es_btf_framework.
data: btf2 type ref to zcl_es_btf_framework.
try.
create object btf
exporting
i_object = '640_TRAIN'
i_tdid = '0001'
i_name = 'TEST01'.
endtry.
btf->read_text( ).
data: xml type xstring.
call method zcl_es_btf_framework=>serialize_me
exporting
i_me = btf
receiving
r_xml = xml.
cl_aunit_assert=>assert_not_initial( act = xml
msg = 'Serialization Failed'(a13) ).
clear btf.
call method zcl_es_btf_framework=>deserialize_me
exporting
i_xml = xml
receiving
r_me = btf2.
cl_aunit_assert=>assert_not_initial( act = btf2
msg = 'Deserialization Failed'(a14) ).
data: l_object type zzes_btf_ttxob,
l_tdid type zzes_btf_tdid,
l_spras type spras,
l_name type tdobname,
l_encoding type string.
call method btf2->get_current_keys
importing
e_object = l_object
e_tdid = l_tdid
e_name = l_name
e_spras = l_spras
e_encoding = l_encoding.
cl_aunit_assert=>assert_equals( act = l_object
exp = '640_TRAIN'
msg = 'Incorrect BTF Text Object'(a03) ).
cl_aunit_assert=>assert_equals( act = l_tdid
exp = '0001'
msg = 'Incorrect BTF Text ID'(a04) ).
cl_aunit_assert=>assert_equals( act = l_name
exp = 'TEST01'
msg = 'Incorrect BTF Text Name'(a05) ).
cl_aunit_assert=>assert_equals( act = l_spras
exp = sy-langu
msg = 'Incorrect BTF Text Language'(a06) ).
cl_aunit_assert=>assert_equals( act = l_encoding
exp = 'utf-8'
msg = 'Incorrect BTF Text Encoding'(a07) ).
cl_aunit_assert=>assert_not_initial( act = btf2->document
msg = 'BTF Document Object is initial'(a08) ).
endmethod. "test_serialize
method test_create_delete.
data: btf type ref to zcl_es_btf_framework.
try.
create object btf
exporting
i_object = '640_TRAIN'
i_tdid = '0001'.
endtry.
data: l_name type tdobname.
data: i_number type i.
data: s_number(25) type c.
data: random_int type ref to cl_abap_random.
data: l_seed type i.
l_seed = cl_abap_random=>seed( ).
random_int = cl_abap_random=>create( l_seed ).
i_number = random_int->intinrange( low = 1
high = 999999999 ).
write i_number to s_number.
concatenate 'ABAP_UNIT_CREATE_TEST_'
s_number
into l_name.
condense l_name no-gaps.
data: l_text type string.
data: l_date(10) type c.
data: l_time(8) type c.
write sy-datum to l_date.
write sy-uzeit to l_time.
concatenate 'Unit Test Text inserted on'
l_date
l_time
'by'
sy-uname
into l_text
separated by space.
call method btf->create_text
exporting
i_name = l_name
i_text = l_text.
btf->save_text( ).
commit work and wait.
data: icontent type zes_btf_content.
select single * from zes_btf_content into icontent
where btf_obj = '640_TRAIN
' and btf_id = '0001'
and btf_name = l_name
and btf_spras = sy-langu.
cl_aunit_assert=>assert_equals( act = icontent-encoding
exp = 'utf-8'
msg = 'BTF Encoding Not Set'(a20) ).
cl_aunit_assert=>assert_equals( act = icontent-btf_user
exp = sy-uname
msg = 'BTF Created By Not Set'(a17) ).
cl_aunit_assert=>assert_equals( act = icontent-btf_date
exp = sy-datum
msg = 'BTF Created Date Not Set'(a18) ).
cl_aunit_assert=>assert_equals( act = icontent-btf_uuser
exp = sy-uname
msg = 'BTF Last Updated By Not Set'(a09) ).
cl_aunit_assert=>assert_equals( act = icontent-btf_udate
exp = sy-datum
msg = 'BTF Last Updated Date Not Set'(a10) ).
cl_aunit_assert=>assert_not_initial( act = icontent-btf_content
msg = 'BTF Content on Create is initial'(a15) ).
data: begin_time type syuzeit.
begin_time = sy-uzeit - 60.
if icontent-btf_utime < begin_time or
icontent-btf_utime > sy-uzeit.
cl_aunit_assert=>fail( msg = 'BTF Last Update Time is not within acceptable bounds'(a11) ).
endif.
begin_time = sy-uzeit - 60.
if icontent-btf_time < begin_time or
icontent-btf_time > sy-uzeit.
cl_aunit_assert=>fail( msg = 'BTF Create Time is not within acceptable bounds'(a19) ).
endif.
btf->delete_text( ).
commit work and wait.
select single * from zes_btf_content into icontent
where btf_obj = '640_TRAIN'
and btf_id = '0001'
and btf_name = l_name
and btf_spras = sy-langu.
if sy-subrc = 0.
cl_aunit_assert=>fail( msg = 'BTF Delete Failed'(a21) ).
endif.
endmethod. "test_create_delete
endclass. "lcl_my_unit_test IMPLEMENTATIONThe ABAP Unit Use
Executing the ABAP Unit test is really quite simple. It can be ran from the test options in SE80 or as part of the Code Inspector (transaction SCI). The following shows one menu path to reach the Unit Test.
If your unit test passes, you receive a status message to that effect. However I wanted to demonstrate the screens you see when a test condition fails. That turned out to be not that difficult. The first time I executed my Unit Test after adding it to my class, I actually failed on a valid condition I had never caught before. The following are some screen shots of the test failure screens.
Closing
For those of you who are interested in putting the BTF technology to work, I hope this weblog will serve as one more example to learn from. Even if you aren't interested in BTF, I hope that you took away some learnings on persistent objects or maybe even ABAP Unit.
- SAP Managed Tags:
8 Comments
